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