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