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(short unsigned int);
 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(short unsigned int);
 364
 365     /**
 366         Sets the millisecond without changing other date components.
 367     */
 368     wxDateTime& SetMillisecond(short unsigned int);
 369
 370     /**
 371         Sets the minute without changing other date components.
 372     */
 373     wxDateTime& SetMinute(short unsigned int);
 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(short unsigned int);
 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 wxChar* 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,
1108                                  int year = Inv_Year);
1109
1110     /**
1111         The effect of calling this function is the same as of calling
1112         @c SetToWeekDay(-1, weekday, month, year). The date will be set to the
1113         last @a weekday in the given month and year (the current ones by
1114         default). Always returns @true.
1115     */
1116     bool SetToLastWeekDay(WeekDay weekday, Month month = Inv_Month,
1117                           int year = Inv_Year);
1118
1119     /**
1120         Sets the date so that it will be the first @a weekday following the
1121         current date.
1122
1123         @return The reference to the modified object itself.
1124     */
1125     wxDateTime& SetToNextWeekDay(WeekDay weekday);
1126
1127     /**
1128         Sets the date so that it will be the last @a weekday before the current
1129         date.
1130
1131         @return The reference to the modified object itself.
1132     */
1133     wxDateTime& SetToPrevWeekDay(WeekDay weekday);
1134
1135     /**
1136         Sets the date to the @e n-th @a weekday in the given month of the given
1137         year (the current month and year are used by default). The parameter
1138         @a n may be either positive (counting from the beginning of the month)
1139         or negative (counting from the end of it).
1140
1141         For example, SetToWeekDay(2, wxDateTime::Wed) will set the date to the
1142         second Wednesday in the current month and
1143         SetToWeekDay(-1, wxDateTime::Sun) will set the date to the last Sunday
1144         in the current month.
1145
1146         @return @true if the date was modified successfully, @false otherwise
1147                  meaning that the specified date doesn't exist.
1148     */
1149     bool SetToWeekDay(WeekDay weekday, int n = 1,
1150                        Month month = Inv_Month, int year = Inv_Year);
1151
1152     /**
1153         Adjusts the date so that it will still lie in the same week as before,
1154         but its week day will be the given one.
1155
1156         @return The reference to the modified object itself.
1157     */
1158     wxDateTime SetToWeekDayInSameWeek(WeekDay weekday,
1159                                       WeekFlags flags = Monday_First);
1160
1161     /**
1162         Sets the date to the day number @a yday in the same year (i.e., unlike
1163         the other functions, this one does not use the current year). The day
1164         number should be in the range 1-366 for the leap years and 1-365 for
1165         the other ones.
1166
1167         @return The reference to the modified object itself.
1168     */
1169     wxDateTime& SetToYearDay(wxDateTime_t yday);
1170
1171     //@}
1172
1173
1174
1175     /**
1176         @name Astronomical/Historical Functions
1177
1178         Some degree of support for the date units used in astronomy and/or
1179         history is provided. You can construct a wxDateTime object from a
1180         JDN and you may also get its JDN, MJD or Rata Die number from it.
1181
1182         Related functions in other groups: wxDateTime(double), Set(double)
1183     */
1184     //@{
1185
1186     /**
1187         Synonym for GetJulianDayNumber().
1188     */
1189     double GetJDN() const;
1190
1191     /**
1192         Returns the JDN corresponding to this date. Beware of rounding errors!
1193
1194         @see GetModifiedJulianDayNumber()
1195     */
1196     double GetJulianDayNumber() const;
1197
1198     /**
1199         Synonym for GetModifiedJulianDayNumber().
1200     */
1201     double GetMJD() const;
1202
1203     /**
1204         Returns the @e "Modified Julian Day Number" (MJD) which is, by
1205         definition, is equal to JDN - 2400000.5.
1206         The MJDs are simpler to work with as the integral MJDs correspond to
1207         midnights of the dates in the Gregorian calendar and not the noons like
1208         JDN. The MJD 0 represents Nov 17, 1858.
1209     */
1210     double GetModifiedJulianDayNumber() const;
1211
1212     /**
1213         Return the @e Rata Die number of this date.
1214
1215         By definition, the Rata Die number is a date specified as the number of
1216         days relative to a base date of December 31 of the year 0. Thus January
1217         1 of the year 1 is Rata Die day 1.
1218     */
1219     double GetRataDie() const;
1220
1221     //@}
1222
1223
1224
1225     /**
1226         @name Time Zone and DST Support
1227
1228         Please see the @ref overview_datetime_timezones "time zone overview"
1229         for more information about time zones. Normally, these functions should
1230         be rarely used.
1231
1232         Related functions in other groups: GetBeginDST(), GetEndDST()
1233     */
1234     //@{
1235
1236     /**
1237         Transform the date from the given time zone to the local one. If
1238         @a noDST is @true, no DST adjustments will be made.
1239
1240         @return The date in the local time zone.
1241     */
1242     wxDateTime FromTimezone(const TimeZone& tz, bool noDST = false) const;
1243
1244     /**
1245         Returns @true if the DST is applied for this date in the given country.
1246
1247         @see GetBeginDST(), GetEndDST()
1248     */
1249     int IsDST(Country country = Country_Default) const;
1250
1251     /**
1252         Same as FromTimezone() but modifies the object in place.
1253     */
1254     wxDateTime MakeFromTimezone(const TimeZone& tz, bool noDST = false);
1255
1256     /**
1257         Modifies the object in place to represent the date in another time
1258         zone. If @a noDST is @true, no DST adjustments will be made.
1259     */
1260     wxDateTime MakeTimezone(const TimeZone& tz, bool noDST = false);
1261
1262     /**
1263         This is the same as calling MakeTimezone() with the argument @c GMT0.
1264     */
1265     wxDateTime& MakeUTC(bool noDST = false);
1266
1267     /**
1268         Transform the date to the given time zone. If @a noDST is @true, no DST
1269         adjustments will be made.
1270
1271         @return The date in the new time zone.
1272     */
1273     wxDateTime ToTimezone(const TimeZone& tz, bool noDST = false) const;
1274
1275     /**
1276         This is the same as calling ToTimezone() with the argument @c GMT0.
1277     */
1278     wxDateTime ToUTC(bool noDST = false) const;
1279
1280     //@}
1281
1282
1283
1284
1285
1286     /**
1287         Converts the year in absolute notation (i.e. a number which can be
1288         negative, positive or zero) to the year in BC/AD notation. For the
1289         positive years, nothing is done, but the year 0 is year 1 BC and so for
1290         other years there is a difference of 1.
1291
1292         This function should be used like this:
1293
1294         @code
1295         wxDateTime dt(...);
1296         int y = dt.GetYear();
1297         printf("The year is %d%s", wxDateTime::ConvertYearToBC(y), y > 0 ? "AD" : "BC");
1298         @endcode
1299     */
1300     static int ConvertYearToBC(int year);
1301
1302     /**
1303         Returns the translations of the strings @c AM and @c PM used for time
1304         formatting for the current locale. Either of the pointers may be @NULL
1305         if the corresponding value is not needed.
1306     */
1307     static void GetAmPmStrings(wxString* am, wxString* pm);
1308
1309     /**
1310         Get the beginning of DST for the given country in the given year
1311         (current one by default). This function suffers from limitations
1312         described in the @ref overview_datetime_dst "DST overview".
1313
1314         @see GetEndDST()
1315     */
1316     static wxDateTime GetBeginDST(int year = Inv_Year,
1317                                    Country country = Country_Default);
1318
1319     /**
1320         Returns the end of DST for the given country in the given year (current
1321         one by default).
1322
1323         @see GetBeginDST()
1324     */
1325     static wxDateTime GetEndDST(int year = Inv_Year,
1326                                  Country country = Country_Default);
1327
1328     /**
1329         Get the current century, i.e. first two digits of the year, in given
1330         calendar (only Gregorian is currently supported).
1331     */
1332     static int GetCentury(int year);
1333
1334     /**
1335         Returns the current default country. The default country is used for
1336         DST calculations, for example.
1337
1338         @see SetCountry()
1339     */
1340     static Country GetCountry();
1341
1342     /**
1343         Get the current month in given calendar (only Gregorian is currently
1344         supported).
1345     */
1346     static Month GetCurrentMonth(Calendar cal = Gregorian);
1347
1348     /**
1349         Get the current year in given calendar (only Gregorian is currently
1350         supported).
1351     */
1352     static int GetCurrentYear(Calendar cal = Gregorian);
1353
1354     /**
1355         Gets the full (default) or abbreviated (specify @c Name_Abbr name of
1356         the given month.
1357
1358         @see GetWeekDayName()
1359     */
1360     static wxString GetMonthName(Month month, NameFlags flags = Name_Full);
1361
1362     /**
1363         Returns the number of days in the given year. The only supported value
1364         for @a cal currently is @c Gregorian.
1365
1366         @beginWxPythonOnly
1367         This method is named "GetNumberOfDaysInYear" in wxPython.
1368         @endWxPythonOnly
1369     */
1370     static wxDateTime_t GetNumberOfDays(int year, Calendar cal = Gregorian);
1371
1372     /**
1373         Returns the number of days in the given month of the given year. The
1374         only supported value for @a cal currently is @c Gregorian.
1375
1376         @beginWxPythonOnly
1377         This method is named "GetNumberOfDaysInMonth" in wxPython.
1378         @endWxPythonOnly
1379     */
1380     static wxDateTime_t GetNumberOfDays(Month month, int year = Inv_Year,
1381                                         Calendar cal = Gregorian);
1382
1383     /**
1384         Returns the current time.
1385     */
1386     static time_t GetTimeNow();
1387
1388     /**
1389         Returns the current time broken down using the buffer whose adress is
1390         passed to the function with @a tm to store the result.
1391     */
1392     static struct tm* GetTmNow(struct tm *tm);
1393
1394     /**
1395         Returns the current time broken down. Note that this function returns a
1396         pointer to a static buffer that's reused by calls to this function and
1397         certain C library functions (e.g. localtime). If there is any chance
1398         your code might be used in a multi-threaded application, you really
1399         should use GetTmNow(struct tm *) instead.
1400     */
1401     static struct tm* GetTmNow();
1402
1403     /**
1404         Gets the full (default) or abbreviated (specify @c Name_Abbr) name of
1405         the given week day.
1406
1407         @see GetMonthName()
1408     */
1409     static wxString GetWeekDayName(WeekDay weekday,
1410                                     NameFlags flags = Name_Full);
1411
1412     /**
1413         Returns @true if DST was used in the given year (the current one by
1414         default) in the given country.
1415     */
1416     static bool IsDSTApplicable(int year = Inv_Year,
1417                                   Country country = Country_Default);
1418
1419     /**
1420         Returns @true if the @a year is a leap one in the specified calendar.
1421         This functions supports Gregorian and Julian calendars.
1422     */
1423     static bool IsLeapYear(int year = Inv_Year, Calendar cal = Gregorian);
1424
1425     /**
1426         This function returns @true if the specified (or default) country is
1427         one of Western European ones. It is used internally by wxDateTime to
1428         determine the DST convention and date and time formatting rules.
1429     */
1430     static bool IsWestEuropeanCountry(Country country = Country_Default);
1431
1432     /**
1433         Returns the object corresponding to the current time.
1434
1435         Example:
1436
1437         @code
1438         wxDateTime now = wxDateTime::Now();
1439         printf("Current time in Paris:\t%s\n", now.Format("%c", wxDateTime::CET).c_str());
1440         @endcode
1441
1442         @note This function is accurate up to seconds. UNow() should be used
1443               for better precision, but it is less efficient and might not be
1444               available on all platforms.
1445
1446         @see Today()
1447     */
1448     static wxDateTime Now();
1449
1450     /**
1451         Sets the country to use by default. This setting influences the DST
1452         calculations, date formatting and other things.
1453
1454         The possible values for @a country parameter are enumerated in the
1455         @ref datetime_constants section.
1456
1457         @see GetCountry()
1458     */
1459     static void SetCountry(Country country);
1460
1461     /**
1462         Set the date to the given @a weekday in the week number @a numWeek of
1463         the given @a year . The number should be in range 1-53.
1464
1465         Note that the returned date may be in a different year than the one
1466         passed to this function because both the week 1 and week 52 or 53 (for
1467         leap years) contain days from different years. See GetWeekOfYear() for
1468         the explanation of how the year weeks are counted.
1469     */
1470     static wxDateTime SetToWeekOfYear(int year, wxDateTime_t numWeek,
1471                                        WeekDay weekday = Mon);
1472
1473     /**
1474         Returns the object corresponding to the midnight of the current day
1475         (i.e. the same as Now(), but the time part is set to 0).
1476
1477         @see Now()
1478     */
1479     static wxDateTime Today();
1480
1481     /**
1482         Returns the object corresponding to the current time including the
1483         milliseconds if a function to get time with such precision is available
1484         on the current platform (supported under most Unices and Win32).
1485
1486         @see Now()
1487     */
1488     static wxDateTime UNow();
1489 };
1490
1491 /**
1492     Global instance of an empty wxDateTime object.
1493
1494     @todo Would it be better to rename this wxNullDateTime so it's consistent
1495           with the rest of the "empty/invalid/null" global objects?
1496 */
1497 const wxDateTime wxDefaultDateTime;
1498
1499
1500
1501 /**
1502     @class wxDateTimeWorkDays
1503
1504     @todo Write wxDateTimeWorkDays documentation.
1505
1506     @library{wxbase}
1507     @category{data}
1508 */
1509 class wxDateTimeWorkDays
1510 {
1511 public:
1512
1513 };
1514
1515
1516
1517 /**
1518     @class wxDateSpan
1519
1520     This class is a "logical time span" and is useful for implementing program
1521     logic for such things as "add one month to the date" which, in general,
1522     doesn't mean to add 60*60*24*31 seconds to it, but to take the same date
1523     the next month (to understand that this is indeed different consider adding
1524     one month to Feb, 15 -- we want to get Mar, 15, of course).
1525
1526     When adding a month to the date, all lesser components (days, hours, ...)
1527     won't be changed unless the resulting date would be invalid: for example,
1528     Jan 31 + 1 month will be Feb 28, not (non-existing) Feb 31.
1529
1530     Because of this feature, adding and subtracting back again the same
1531     wxDateSpan will @b not, in general, give back the original date: Feb 28 - 1
1532     month will be Jan 28, not Jan 31!
1533
1534     wxDateSpan objects can be either positive or negative. They may be
1535     multiplied by scalars which multiply all deltas by the scalar: i.e.
1536     2*(1  month and  1  day) is 2 months and 2 days. They can be added together
1537     with wxDateTime or wxTimeSpan, but the type of result is different for each
1538     case.
1539
1540     @warning If you specify both weeks and days, the total number of days added
1541              will be 7*weeks + days! See also GetTotalDays().
1542
1543     Equality operators are defined for wxDateSpans. Two wxDateSpans are equal
1544     if and only if they both give the same target date when added to @b every
1545     source date. Thus wxDateSpan::Months(1) is not equal to
1546     wxDateSpan::Days(30), because they don't give the same date when added to
1547     Feb 1st. But wxDateSpan::Days(14) is equal to wxDateSpan::Weeks(2).
1548
1549     Finally, notice that for adding hours, minutes and so on you don't need
1550     this class at all: wxTimeSpan will do the job because there are no
1551     subtleties associated with those (we don't support leap seconds).
1552
1553     @library{wxbase}
1554     @category{data}
1555
1556     @see @ref overview_datetime, wxDateTime
1557 */
1558 class wxDateSpan
1559 {
1560 public:
1561     /**
1562         Constructs the date span object for the given number of years, months,
1563         weeks and days. Note that the weeks and days add together if both are
1564         given.
1565     */
1566     wxDateSpan(int years = 0, int months = 0, int weeks = 0, int days = 0);
1567
1568     /**
1569         Returns the sum of two date spans.
1570
1571         @return A new wxDateSpan object with the result.
1572     */
1573     wxDateSpan Add(const wxDateSpan& other) const;
1574     /**
1575         Adds the given wxDateSpan to this wxDateSpan and returns a reference
1576         to itself.
1577     */
1578     wxDateSpan& Add(const wxDateSpan& other);
1579
1580     /**
1581         Returns a date span object corresponding to one day.
1582
1583         @see Days()
1584     */
1585     static wxDateSpan Day();
1586
1587     /**
1588         Returns a date span object corresponding to the given number of days.
1589
1590         @see Day()
1591     */
1592     static wxDateSpan Days(int days);
1593
1594     /**
1595         Returns the number of days (not counting the weeks component) in this
1596         date span.
1597
1598         @see GetTotalDays()
1599     */
1600     int GetDays() const;
1601
1602     /**
1603         Returns the number of the months (not counting the years) in this date
1604         span.
1605     */
1606     int GetMonths() const;
1607
1608     /**
1609         Returns the combined number of days in this date span, counting both
1610         weeks and days. This doesn't take months or years into account.
1611
1612         @see GetWeeks(), GetDays()
1613     */
1614     int GetTotalDays() const;
1615
1616     /**
1617         Returns the number of weeks in this date span.
1618
1619         @see GetTotalDays()
1620     */
1621     int GetWeeks() const;
1622
1623     /**
1624         Returns the number of years in this date span.
1625     */
1626     int GetYears() const;
1627
1628     /**
1629         Returns a date span object corresponding to one month.
1630
1631         @see Months()
1632     */
1633     static wxDateSpan Month();
1634
1635     /**
1636         Returns a date span object corresponding to the given number of months.
1637
1638         @see Month()
1639     */
1640     static wxDateSpan Months(int mon);
1641
1642     /**
1643         Returns the product of the date span by the specified @a factor. The
1644         product is computed by multiplying each of the components by the
1645         @a factor.
1646
1647         @return A new wxDateSpan object with the result.
1648     */
1649     wxDateSpan Multiply(int factor) const;
1650     /**
1651         Multiplies this date span by the specified @a factor. The product is
1652         computed by multiplying each of the components by the @a factor.
1653
1654         @return A reference to this wxDateSpan object modified in place.
1655     */
1656     wxDateSpan& Multiply(int factor);
1657
1658     /**
1659         Changes the sign of this date span.
1660
1661         @see Negate()
1662     */
1663     wxDateSpan& Neg();
1664
1665     /**
1666         Returns a date span with the opposite sign.
1667
1668         @see Neg()
1669     */
1670     wxDateSpan Negate() const;
1671
1672     /**
1673         Sets the number of days (without modifying any other components) in
1674         this date span.
1675     */
1676     wxDateSpan& SetDays(int n);
1677
1678     /**
1679         Sets the number of months (without modifying any other components) in
1680         this date span.
1681     */
1682     wxDateSpan& SetMonths(int n);
1683
1684     /**
1685         Sets the number of weeks (without modifying any other components) in
1686         this date span.
1687     */
1688     wxDateSpan& SetWeeks(int n);
1689
1690     /**
1691         Sets the number of years (without modifying any other components) in
1692         this date span.
1693     */
1694     wxDateSpan& SetYears(int n);
1695
1696     /**
1697         Returns the difference of two date spans.
1698
1699         @return A new wxDateSpan object with the result.
1700     */
1701     wxDateSpan Subtract(const wxDateSpan& other) const;
1702     /**
1703         Subtracts the given wxDateSpan to this wxDateSpan and returns a
1704         reference to itself.
1705     */
1706     wxDateSpan& Subtract(const wxDateSpan& other);
1707
1708     /**
1709         Returns a date span object corresponding to one week.
1710
1711         @see Weeks()
1712     */
1713     static wxDateSpan Week();
1714
1715     /**
1716         Returns a date span object corresponding to the given number of weeks.
1717
1718         @see Week()
1719     */
1720     static wxDateSpan Weeks(int weeks);
1721
1722     /**
1723         Returns a date span object corresponding to one year.
1724
1725         @see Years()
1726     */
1727     static wxDateSpan Year();
1728
1729     /**
1730         Returns a date span object corresponding to the given number of years.
1731
1732         @see Year()
1733     */
1734     static wxDateSpan Years(int years);
1735
1736     /**
1737         Adds the given wxDateSpan to this wxDateSpan and returns the result.
1738     */
1739     wxDateSpan& operator+=(const wxDateSpan& other);
1740
1741     /**
1742         Subtracts the given wxDateSpan to this wxDateSpan and returns the
1743         result.
1744     */
1745     wxDateSpan& operator-=(const wxDateSpan& other);
1746
1747     /**
1748         Changes the sign of this date span.
1749
1750         @see Negate()
1751     */
1752     wxDateSpan& operator-();
1753
1754     /**
1755         Multiplies this date span by the specified @a factor. The product is
1756         computed by multiplying each of the components by the @a factor.
1757
1758         @return A reference to this wxDateSpan object modified in place.
1759     */
1760     wxDateSpan& operator*=(int factor);
1761
1762     /**
1763         Returns @true if this date span is different from the other one.
1764     */
1765     bool operator!=(const wxDateSpan&) const;
1766
1767     /**
1768         Returns @true if this date span is equal to the other one. Two date
1769         spans are considered equal if and only if they have the same number of
1770         years and months and the same total number of days (counting both days
1771         and weeks).
1772     */
1773     bool operator==(const wxDateSpan&) const;
1774 };
1775
1776
1777
1778 /**
1779     @class wxTimeSpan
1780
1781     wxTimeSpan class represents a time interval.
1782
1783     @library{wxbase}
1784     @category{data}
1785
1786     @see @ref overview_datetime, wxDateTime
1787 */
1788 class wxTimeSpan
1789 {
1790 public:
1791     /**
1792         Default constructor, constructs a zero timespan.
1793     */
1794     wxTimeSpan();
1795     /**
1796         Constructs timespan from separate values for each component, with the
1797         date set to 0. Hours are not restricted to 0-24 range, neither are
1798         minutes, seconds or milliseconds.
1799     */
1800     wxTimeSpan(long hours, long min = 0, wxLongLong sec = 0, wxLongLong msec = 0);
1801
1802     /**
1803         Returns the absolute value of the timespan: does not modify the object.
1804     */
1805     wxTimeSpan Abs() const;
1806
1807     /**
1808         Returns the sum of two time spans.
1809
1810         @return A new wxDateSpan object with the result.
1811     */
1812     wxTimeSpan Add(const wxTimeSpan& diff) const;
1813     /**
1814         Adds the given wxTimeSpan to this wxTimeSpan and returns a reference
1815         to itself.
1816     */
1817     wxTimeSpan& Add(const wxTimeSpan& diff);
1818
1819     /**
1820         Returns the timespan for one day.
1821     */
1822     static wxTimespan Day();
1823
1824     /**
1825         Returns the timespan for the given number of days.
1826     */
1827     static wxTimespan Days(long days);
1828
1829     /**
1830         Returns the string containing the formatted representation of the time
1831         span. The following format specifiers are allowed after %:
1832
1833         - @c H - Number of Hours
1834         - @c M - Number of Minutes
1835         - @c S - Number of Seconds
1836         - @c l - Number of Milliseconds
1837         - @c D - Number of Days
1838         - @c E - Number of Weeks
1839         - @c % - The percent character
1840
1841         Note that, for example, the number of hours in the description above is
1842         not well defined: it can be either the total number of hours (for
1843         example, for a time span of 50 hours this would be 50) or just the hour
1844         part of the time span, which would be 2 in this case as 50 hours is
1845         equal to 2 days and 2 hours.
1846
1847         wxTimeSpan resolves this ambiguity in the following way: if there had
1848         been, indeed, the @c %D format specified preceding the @c %H, then it
1849         is interpreted as 2. Otherwise, it is 50.
1850
1851         The same applies to all other format specifiers: if they follow a
1852         specifier of larger unit, only the rest part is taken, otherwise the
1853         full value is used.
1854     */
1855     wxString Format(const wxString& = wxDefaultTimeSpanFormat) const;
1856
1857     /**
1858         Returns the difference in number of days.
1859     */
1860     int GetDays() const;
1861
1862     /**
1863         Returns the difference in number of hours.
1864     */
1865     int GetHours() const;
1866
1867     /**
1868         Returns the difference in number of milliseconds.
1869     */
1870     wxLongLong GetMilliseconds() const;
1871
1872     /**
1873         Returns the difference in number of minutes.
1874     */
1875     int GetMinutes() const;
1876
1877     /**
1878         Returns the difference in number of seconds.
1879     */
1880     wxLongLong GetSeconds() const;
1881
1882     /**
1883         Returns the internal representation of timespan.
1884     */
1885     wxLongLong GetValue() const;
1886
1887     /**
1888         Returns the difference in number of weeks.
1889     */
1890     int GetWeeks() const;
1891
1892     /**
1893         Returns the timespan for one hour.
1894     */
1895     static wxTimespan Hour();
1896
1897     /**
1898         Returns the timespan for the given number of hours.
1899     */
1900     static wxTimespan Hours(long hours);
1901
1902     /**
1903         Returns @true if two timespans are equal.
1904     */
1905     bool IsEqualTo(const wxTimeSpan& ts) const;
1906
1907     /**
1908         Compares two timespans: works with the absolute values, i.e. -2 hours
1909         is longer than 1 hour. Also, it will return @false if the timespans are
1910         equal in absolute value.
1911     */
1912     bool IsLongerThan(const wxTimeSpan& ts) const;
1913
1914     /**
1915         Returns @true if the timespan is negative.
1916     */
1917     bool IsNegative() const;
1918
1919     /**
1920         Returns @true if the timespan is empty.
1921     */
1922     bool IsNull() const;
1923
1924     /**
1925         Returns @true if the timespan is positive.
1926     */
1927     bool IsPositive() const;
1928
1929     /**
1930         Compares two timespans: works with the absolute values, i.e. 1 hour is
1931         shorter than -2 hours. Also, it will return @false if the timespans are
1932         equal in absolute value.
1933     */
1934     bool IsShorterThan(const wxTimeSpan& ts) const;
1935
1936     /**
1937         Returns the timespan for one millisecond.
1938     */
1939     static wxTimespan Millisecond();
1940
1941     /**
1942         Returns the timespan for the given number of milliseconds.
1943     */
1944     static wxTimespan Milliseconds(long ms);
1945
1946     /**
1947         Returns the timespan for one minute.
1948     */
1949     static wxTimespan Minute();
1950
1951     /**
1952         Returns the timespan for the given number of minutes.
1953     */
1954     static wxTimespan Minutes(long min);
1955
1956     /**
1957         Returns the product of this time span by @a n.
1958
1959         @return A new wxTimeSpan object with the result.
1960     */
1961     wxTimeSpan Multiply(int n) const;
1962     /**
1963         Multiplies this time span by @a n.
1964
1965         @return A reference to this wxTimeSpan object modified in place.
1966     */
1967     wxTimeSpan& Multiply(int n);
1968
1969     /**
1970         Negate the value of the timespan.
1971
1972         @see Negate()
1973     */
1974     wxTimeSpan& Neg();
1975
1976     /**
1977         Returns timespan with inverted sign.
1978
1979         @see Neg()
1980     */
1981     wxTimeSpan Negate() const;
1982
1983     /**
1984         Returns the timespan for one second.
1985     */
1986     static wxTimespan Second();
1987
1988     /**
1989         Returns the timespan for the given number of seconds.
1990     */
1991     static wxTimespan Seconds(long sec);
1992
1993     /**
1994         Returns the difference of two time spans.
1995
1996         @return A new wxDateSpan object with the result.
1997     */
1998     wxTimeSpan Subtract(const wxTimeSpan& diff) const;
1999     /**
2000         Subtracts the given wxTimeSpan to this wxTimeSpan and returns a
2001         reference to itself.
2002     */
2003     wxTimeSpan& Subtract(const wxTimeSpan& diff);
2004
2005     /**
2006         Returns the timespan for one week.
2007     */
2008     static wxTimespan Week();
2009
2010     /**
2011         Returns the timespan for the given number of weeks.
2012     */
2013     static wxTimespan Weeks(long weeks);
2014
2015     /**
2016         Adds the given wxTimeSpan to this wxTimeSpan and returns the result.
2017     */
2018     wxTimeSpan& operator+=(const wxTimeSpan& diff);
2019
2020     /**
2021         Multiplies this time span by @a n.
2022
2023         @return A reference to this wxTimeSpan object modified in place.
2024     */
2025     wxTimeSpan& operator*=(int n);
2026
2027     /**
2028         Negate the value of the timespan.
2029
2030         @see Negate()
2031     */
2032     wxTimeSpan& operator-();
2033
2034     /**
2035         Subtracts the given wxTimeSpan to this wxTimeSpan and returns the
2036         result.
2037     */
2038     wxTimeSpan& operator-=(const wxTimeSpan& diff);
2039 };
2040
2041
2042
2043 /**
2044     @class wxDateTimeHolidayAuthority
2045
2046     @todo Write wxDateTimeHolidayAuthority documentation.
2047
2048     @library{wxbase}
2049     @category{misc}
2050 */
2051 class wxDateTimeHolidayAuthority
2052 {
2053 public:
2054
2055 };
2056