interface/wx/datetime.h

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