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