Fix QDateTime::toString for Qt::ISODate
[qt:qt.git] / src / corelib / tools / qdatetime.cpp
1 /****************************************************************************
2 **
3 ** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
4 ** All rights reserved.
5 ** Contact: Nokia Corporation (qt-info@nokia.com)
6 **
7 ** This file is part of the QtCore module of the Qt Toolkit.
8 **
9 ** $QT_BEGIN_LICENSE:LGPL$
10 ** No Commercial Usage
11 ** This file contains pre-release code and may not be distributed.
12 ** You may use this file in accordance with the terms and conditions
13 ** contained in the Technology Preview License Agreement accompanying
14 ** this package.
15 **
16 ** GNU Lesser General Public License Usage
17 ** Alternatively, this file may be used under the terms of the GNU Lesser
18 ** General Public License version 2.1 as published by the Free Software
19 ** Foundation and appearing in the file LICENSE.LGPL included in the
20 ** packaging of this file.  Please review the following information to
21 ** ensure the GNU Lesser General Public License version 2.1 requirements
22 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
23 **
24 ** In addition, as a special exception, Nokia gives you certain additional
25 ** rights.  These rights are described in the Nokia Qt LGPL Exception
26 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
27 **
28 ** If you have questions regarding the use of this file, please contact
29 ** Nokia at qt-info@nokia.com.
30 **
31 **
32 **
33 **
34 **
35 **
36 **
37 **
38 ** $QT_END_LICENSE$
39 **
40 ****************************************************************************/
41
42 #include "qplatformdefs.h"
43 #include "private/qdatetime_p.h"
44
45 #include "qdatastream.h"
46 #include "qset.h"
47 #include "qlocale.h"
48 #include "qdatetime.h"
49 #include "qregexp.h"
50 #include "qdebug.h"
51 #if defined(Q_OS_WIN32) || defined(Q_OS_WINCE)
52 #include <qt_windows.h>
53 #endif
54 #ifndef Q_WS_WIN
55 #include <locale.h>
56 #endif
57
58 #include <time.h>
59 #if defined(Q_OS_WINCE)
60 #include "qfunctions_wince.h"
61 #endif
62
63 //#define QDATETIMEPARSER_DEBUG
64 #if defined (QDATETIMEPARSER_DEBUG) && !defined(QT_NO_DEBUG_STREAM)
65 #  define QDTPDEBUG qDebug() << QString("%1:%2").arg(__FILE__).arg(__LINE__)
66 #  define QDTPDEBUGN qDebug
67 #else
68 #  define QDTPDEBUG if (false) qDebug()
69 #  define QDTPDEBUGN if (false) qDebug
70 #endif
71
72 #if defined(Q_WS_MAC)
73 #include <private/qcore_mac_p.h>
74 #endif
75
76 #if defined(Q_OS_SYMBIAN)
77 #include <e32std.h>
78 #endif
79
80 QT_BEGIN_NAMESPACE
81
82 enum {
83     FIRST_YEAR = -4713,
84     FIRST_MONTH = 1,
85     FIRST_DAY = 2,  // ### Qt 5: make FIRST_DAY = 1, by support jd == 0 as valid
86     SECS_PER_DAY = 86400,
87     MSECS_PER_DAY = 86400000,
88     SECS_PER_HOUR = 3600,
89     MSECS_PER_HOUR = 3600000,
90     SECS_PER_MIN = 60,
91     MSECS_PER_MIN = 60000,
92     JULIAN_DAY_FOR_EPOCH = 2440588 // result of julianDayFromGregorianDate(1970, 1, 1)
93 };
94
95 static inline QDate fixedDate(int y, int m, int d)
96 {
97     QDate result(y, m, 1);
98     result.setDate(y, m, qMin(d, result.daysInMonth()));
99     return result;
100 }
101
102 static inline uint julianDayFromGregorianDate(int year, int month, int day)
103 {
104     // Gregorian calendar starting from October 15, 1582
105     // Algorithm from Henry F. Fliegel and Thomas C. Van Flandern
106     return (1461 * (year + 4800 + (month - 14) / 12)) / 4
107            + (367 * (month - 2 - 12 * ((month - 14) / 12))) / 12
108            - (3 * ((year + 4900 + (month - 14) / 12) / 100)) / 4
109            + day - 32075;
110 }
111
112 static uint julianDayFromDate(int year, int month, int day)
113 {
114     if (year < 0)
115         ++year;
116
117     if (year > 1582 || (year == 1582 && (month > 10 || (month == 10 && day >= 15)))) {
118         return julianDayFromGregorianDate(year, month, day);
119     } else if (year < 1582 || (year == 1582 && (month < 10 || (month == 10 && day <= 4)))) {
120         // Julian calendar until October 4, 1582
121         // Algorithm from Frequently Asked Questions about Calendars by Claus Toendering
122         int a = (14 - month) / 12;
123         return (153 * (month + (12 * a) - 3) + 2) / 5
124                + (1461 * (year + 4800 - a)) / 4
125                + day - 32083;
126     } else {
127         // the day following October 4, 1582 is October 15, 1582
128         return 0;
129     }
130 }
131
132 static void getDateFromJulianDay(uint julianDay, int *year, int *month, int *day)
133 {
134     int y, m, d;
135
136     if (julianDay >= 2299161) {
137         // Gregorian calendar starting from October 15, 1582
138         // This algorithm is from Henry F. Fliegel and Thomas C. Van Flandern
139         qulonglong ell, n, i, j;
140         ell = qulonglong(julianDay) + 68569;
141         n = (4 * ell) / 146097;
142         ell = ell - (146097 * n + 3) / 4;
143         i = (4000 * (ell + 1)) / 1461001;
144         ell = ell - (1461 * i) / 4 + 31;
145         j = (80 * ell) / 2447;
146         d = ell - (2447 * j) / 80;
147         ell = j / 11;
148         m = j + 2 - (12 * ell);
149         y = 100 * (n - 49) + i + ell;
150     } else {
151         // Julian calendar until October 4, 1582
152         // Algorithm from Frequently Asked Questions about Calendars by Claus Toendering
153         julianDay += 32082;
154         int dd = (4 * julianDay + 3) / 1461;
155         int ee = julianDay - (1461 * dd) / 4;
156         int mm = ((5 * ee) + 2) / 153;
157         d = ee - (153 * mm + 2) / 5 + 1;
158         m = mm + 3 - 12 * (mm / 10);
159         y = dd - 4800 + (mm / 10);
160         if (y <= 0)
161             --y;
162     }
163     if (year)
164         *year = y;
165     if (month)
166         *month = m;
167     if (day)
168         *day = d;
169 }
170
171
172 static const char monthDays[] = { 0, 31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31 };
173
174 #ifndef QT_NO_TEXTDATE
175 static const char * const qt_shortMonthNames[] = {
176     "Jan", "Feb", "Mar", "Apr", "May", "Jun",
177     "Jul", "Aug", "Sep", "Oct", "Nov", "Dec" };
178 #endif
179 #ifndef QT_NO_DATESTRING
180 static QString fmtDateTime(const QString& f, const QTime* dt = 0, const QDate* dd = 0);
181 #endif
182
183 /*****************************************************************************
184   QDate member functions
185  *****************************************************************************/
186
187 /*!
188     \since 4.5
189
190     \enum QDate::MonthNameType
191
192     This enum describes the types of the string representation used
193     for the month name.
194
195     \value DateFormat This type of name can be used for date-to-string formatting.
196     \value StandaloneFormat This type is used when you need to enumerate months or weekdays.
197            Usually standalone names are represented in singular forms with
198            capitalized first letter.
199 */
200
201 /*!
202     \class QDate
203     \reentrant
204     \brief The QDate class provides date functions.
205
206
207     A QDate object contains a calendar date, i.e. year, month, and day
208     numbers, in the Gregorian calendar. (see \l{QDate G and J} {Use of
209     Gregorian and Julian Calendars} for dates prior to 15 October
210     1582). It can read the current date from the system clock. It
211     provides functions for comparing dates, and for manipulating
212     dates. For example, it is possible to add and subtract days,
213     months, and years to dates.
214
215     A QDate object is typically created either by giving the year,
216     month, and day numbers explicitly. Note that QDate interprets two
217     digit years as is, i.e., years 0 - 99. A QDate can also be
218     constructed with the static function currentDate(), which creates
219     a QDate object containing the system clock's date.  An explicit
220     date can also be set using setDate(). The fromString() function
221     returns a QDate given a string and a date format which is used to
222     interpret the date within the string.
223
224     The year(), month(), and day() functions provide access to the
225     year, month, and day numbers. Also, dayOfWeek() and dayOfYear()
226     functions are provided. The same information is provided in
227     textual format by the toString(), shortDayName(), longDayName(),
228     shortMonthName(), and longMonthName() functions.
229
230     QDate provides a full set of operators to compare two QDate
231     objects where smaller means earlier, and larger means later.
232
233     You can increment (or decrement) a date by a given number of days
234     using addDays(). Similarly you can use addMonths() and addYears().
235     The daysTo() function returns the number of days between two
236     dates.
237
238     The daysInMonth() and daysInYear() functions return how many days
239     there are in this date's month and year, respectively. The
240     isLeapYear() function indicates whether a date is in a leap year.
241
242     \section1
243
244     \target QDate G and J
245     \section2 Use of Gregorian and Julian Calendars
246
247     QDate uses the Gregorian calendar in all locales, beginning
248     on the date 15 October 1582. For dates up to and including 4
249     October 1582, the Julian calendar is used.  This means there is a
250     10-day gap in the internal calendar between the 4th and the 15th
251     of October 1582. When you use QDateTime for dates in that epoch,
252     the day after 4 October 1582 is 15 October 1582, and the dates in
253     the gap are invalid.
254
255     The Julian to Gregorian changeover date used here is the date when
256     the Gregorian calendar was first introduced, by Pope Gregory
257     XIII. That change was not universally accepted and some localities
258     only executed it at a later date (if at all).  QDateTime
259     doesn't take any of these historical facts into account. If an
260     application must support a locale-specific dating system, it must
261     do so on its own, remembering to convert the dates using the
262     Julian day.
263
264     \section2 No Year 0
265
266     There is no year 0. Dates in that year are considered invalid. The
267     year -1 is the year "1 before Christ" or "1 before current era."
268     The day before 0001-01-01 is December 31st, 1 BCE.
269
270     \section2 Range of Valid Dates
271
272     The range of valid dates is from January 2nd, 4713 BCE, to
273     sometime in the year 11 million CE. The Julian Day returned by
274     QDate::toJulianDay() is a number in the contiguous range from 1 to
275     \e{overflow}, even across QDateTime's "date holes". It is suitable
276     for use in applications that must convert a QDateTime to a date in
277     another calendar system, e.g., Hebrew, Islamic or Chinese.
278
279     \sa QTime, QDateTime, QDateEdit, QDateTimeEdit, QCalendarWidget
280 */
281
282 /*!
283     \fn QDate::QDate()
284
285     Constructs a null date. Null dates are invalid.
286
287     \sa isNull(), isValid()
288 */
289
290 /*!
291     Constructs a date with year \a y, month \a m and day \a d.
292
293     If the specified date is invalid, the date is not set and
294     isValid() returns false. A date before 2 January 4713 B.C. is
295     considered invalid.
296
297     \warning Years 0 to 99 are interpreted as is, i.e., years
298              0-99.
299
300     \sa isValid()
301 */
302
303 QDate::QDate(int y, int m, int d)
304 {
305     setDate(y, m, d);
306 }
307
308
309 /*!
310     \fn bool QDate::isNull() const
311
312     Returns true if the date is null; otherwise returns false. A null
313     date is invalid.
314
315     \note The behavior of this function is equivalent to isValid().
316
317     \sa isValid()
318 */
319
320
321 /*!
322     Returns true if this date is valid; otherwise returns false.
323
324     \sa isNull()
325 */
326
327 bool QDate::isValid() const
328 {
329     return !isNull();
330 }
331
332
333 /*!
334     Returns the year of this date. Negative numbers indicate years
335     before 1 A.D. = 1 C.E., such that year -44 is 44 B.C.
336
337     \sa month(), day()
338 */
339
340 int QDate::year() const
341 {
342     int y;
343     getDateFromJulianDay(jd, &y, 0, 0);
344     return y;
345 }
346
347 /*!
348     Returns the number corresponding to the month of this date, using
349     the following convention:
350
351     \list
352     \i 1 = "January"
353     \i 2 = "February"
354     \i 3 = "March"
355     \i 4 = "April"
356     \i 5 = "May"
357     \i 6 = "June"
358     \i 7 = "July"
359     \i 8 = "August"
360     \i 9 = "September"
361     \i 10 = "October"
362     \i 11 = "November"
363     \i 12 = "December"
364     \endlist
365
366     \sa year(), day()
367 */
368
369 int QDate::month() const
370 {
371     int m;
372     getDateFromJulianDay(jd, 0, &m, 0);
373     return m;
374 }
375
376 /*!
377     Returns the day of the month (1 to 31) of this date.
378
379     \sa year(), month(), dayOfWeek()
380 */
381
382 int QDate::day() const
383 {
384     int d;
385     getDateFromJulianDay(jd, 0, 0, &d);
386     return d;
387 }
388
389 /*!
390     Returns the weekday (1 to 7) for this date.
391
392     \sa day(), dayOfYear(), Qt::DayOfWeek
393 */
394
395 int QDate::dayOfWeek() const
396 {
397     return (jd % 7) + 1;
398 }
399
400 /*!
401     Returns the day of the year (1 to 365 or 366 on leap years) for
402     this date.
403
404     \sa day(), dayOfWeek()
405 */
406
407 int QDate::dayOfYear() const
408 {
409     return jd - julianDayFromDate(year(), 1, 1) + 1;
410 }
411
412 /*!
413     Returns the number of days in the month (28 to 31) for this date.
414
415     \sa day(), daysInYear()
416 */
417
418 int QDate::daysInMonth() const
419 {
420     int y, m, d;
421     getDateFromJulianDay(jd, &y, &m, &d);
422     if (m == 2 && isLeapYear(y))
423         return 29;
424     else
425         return monthDays[m];
426 }
427
428 /*!
429     Returns the number of days in the year (365 or 366) for this date.
430
431     \sa day(), daysInMonth()
432 */
433
434 int QDate::daysInYear() const
435 {
436     int y, m, d;
437     getDateFromJulianDay(jd, &y, &m, &d);
438     return isLeapYear(y) ? 366 : 365;
439 }
440
441 /*!
442     Returns the week number (1 to 53), and stores the year in
443     *\a{yearNumber} unless \a yearNumber is null (the default).
444
445     Returns 0 if the date is invalid.
446
447     In accordance with ISO 8601, weeks start on Monday and the first
448     Thursday of a year is always in week 1 of that year. Most years
449     have 52 weeks, but some have 53.
450
451     *\a{yearNumber} is not always the same as year(). For example, 1
452     January 2000 has week number 52 in the year 1999, and 31 December
453     2002 has week number 1 in the year 2003.
454
455     \legalese
456     Copyright (c) 1989 The Regents of the University of California.
457     All rights reserved.
458
459     Redistribution and use in source and binary forms are permitted
460     provided that the above copyright notice and this paragraph are
461     duplicated in all such forms and that any documentation,
462     advertising materials, and other materials related to such
463     distribution and use acknowledge that the software was developed
464     by the University of California, Berkeley.  The name of the
465     University may not be used to endorse or promote products derived
466     from this software without specific prior written permission.
467     THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR
468     IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
469     WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
470
471     \sa isValid()
472 */
473
474 int QDate::weekNumber(int *yearNumber) const
475 {
476     if (!isValid())
477         return 0;
478
479     int year = QDate::year();
480     int yday = dayOfYear() - 1;
481     int wday = dayOfWeek();
482     if (wday == 7)
483         wday = 0;
484     int w;
485
486     for (;;) {
487         int len;
488         int bot;
489         int top;
490
491         len = isLeapYear(year) ? 366 : 365;
492         /*
493         ** What yday (-3 ... 3) does
494         ** the ISO year begin on?
495         */
496         bot = ((yday + 11 - wday) % 7) - 3;
497         /*
498         ** What yday does the NEXT
499         ** ISO year begin on?
500         */
501         top = bot - (len % 7);
502         if (top < -3)
503             top += 7;
504         top += len;
505         if (yday >= top) {
506             ++year;
507             w = 1;
508             break;
509         }
510         if (yday >= bot) {
511             w = 1 + ((yday - bot) / 7);
512             break;
513         }
514         --year;
515         yday += isLeapYear(year) ? 366 : 365;
516     }
517     if (yearNumber != 0)
518         *yearNumber = year;
519     return w;
520 }
521
522 #ifndef QT_NO_TEXTDATE
523 /*!
524     \since 4.5
525
526     Returns the short name of the \a month for the representation specified
527     by \a type.
528
529     The months are enumerated using the following convention:
530
531     \list
532     \i 1 = "Jan"
533     \i 2 = "Feb"
534     \i 3 = "Mar"
535     \i 4 = "Apr"
536     \i 5 = "May"
537     \i 6 = "Jun"
538     \i 7 = "Jul"
539     \i 8 = "Aug"
540     \i 9 = "Sep"
541     \i 10 = "Oct"
542     \i 11 = "Nov"
543     \i 12 = "Dec"
544     \endlist
545
546     The month names will be localized according to the system's locale
547     settings.
548
549     \sa toString(), longMonthName(), shortDayName(), longDayName()
550 */
551
552 QString QDate::shortMonthName(int month, QDate::MonthNameType type)
553 {
554     if (month < 1 || month > 12) {
555         month = 1;
556     }
557     switch (type) {
558     case QDate::DateFormat:
559         return QLocale::system().monthName(month, QLocale::ShortFormat);
560     case QDate::StandaloneFormat:
561         return QLocale::system().standaloneMonthName(month, QLocale::ShortFormat);
562     default:
563         break;
564     }
565     return QString();
566 }
567
568 /*!
569     Returns the short version of the name of the \a month. The
570     returned name is in normal type which can be used for date formatting.
571
572     \sa toString(), longMonthName(), shortDayName(), longDayName()
573  */
574
575 QString QDate::shortMonthName(int month)
576 {
577     return shortMonthName(month, QDate::DateFormat);
578 }
579
580 /*!
581     \since 4.5
582
583     Returns the long name of the \a month for the representation specified
584     by \a type.
585
586     The months are enumerated using the following convention:
587
588     \list
589     \i 1 = "January"
590     \i 2 = "February"
591     \i 3 = "March"
592     \i 4 = "April"
593     \i 5 = "May"
594     \i 6 = "June"
595     \i 7 = "July"
596     \i 8 = "August"
597     \i 9 = "September"
598     \i 10 = "October"
599     \i 11 = "November"
600     \i 12 = "December"
601     \endlist
602
603     The month names will be localized according to the system's locale
604     settings.
605
606     \sa toString(), shortMonthName(), shortDayName(), longDayName()
607 */
608
609 QString QDate::longMonthName(int month, MonthNameType type)
610 {
611     if (month < 1 || month > 12) {
612         month = 1;
613     }
614     switch (type) {
615     case QDate::DateFormat:
616         return QLocale::system().monthName(month, QLocale::LongFormat);
617     case QDate::StandaloneFormat:
618         return QLocale::system().standaloneMonthName(month, QLocale::LongFormat);
619     default:
620         break;
621     }
622     return QString();
623 }
624
625 /*!
626     Returns the long version of the name of the \a month. The
627     returned name is in normal type which can be used for date formatting.
628
629     \sa toString(), shortMonthName(), shortDayName(), longDayName()
630  */
631
632 QString QDate::longMonthName(int month)
633 {
634     if (month < 1 || month > 12) {
635         month = 1;
636     }
637     return QLocale::system().monthName(month, QLocale::LongFormat);
638 }
639
640 /*!
641     \since 4.5
642
643     Returns the short name of the \a weekday for the representation specified
644     by \a type.
645
646     The days are enumerated using the following convention:
647
648     \list
649     \i 1 = "Mon"
650     \i 2 = "Tue"
651     \i 3 = "Wed"
652     \i 4 = "Thu"
653     \i 5 = "Fri"
654     \i 6 = "Sat"
655     \i 7 = "Sun"
656     \endlist
657
658     The day names will be localized according to the system's locale
659     settings.
660
661     \sa toString(), shortMonthName(), longMonthName(), longDayName()
662 */
663
664 QString QDate::shortDayName(int weekday, MonthNameType type)
665 {
666     if (weekday < 1 || weekday > 7) {
667         weekday = 1;
668     }
669     switch (type) {
670     case QDate::DateFormat:
671         return QLocale::system().dayName(weekday, QLocale::ShortFormat);
672     case QDate::StandaloneFormat:
673         return QLocale::system().standaloneDayName(weekday, QLocale::ShortFormat);
674     default:
675         break;
676     }
677     return QString();
678 }
679
680 /*!
681     Returns the short version of the name of the \a weekday. The
682     returned name is in normal type which can be used for date formatting.
683
684     \sa toString(), longDayName(), shortMonthName(), longMonthName()
685  */
686
687 QString QDate::shortDayName(int weekday)
688 {
689     if (weekday < 1 || weekday > 7) {
690         weekday = 1;
691     }
692     return QLocale::system().dayName(weekday, QLocale::ShortFormat);
693 }
694
695 /*!
696     \since 4.5
697
698     Returns the long name of the \a weekday for the representation specified
699     by \a type.
700
701     The days are enumerated using the following convention:
702
703     \list
704     \i 1 = "Monday"
705     \i 2 = "Tuesday"
706     \i 3 = "Wednesday"
707     \i 4 = "Thursday"
708     \i 5 = "Friday"
709     \i 6 = "Saturday"
710     \i 7 = "Sunday"
711     \endlist
712
713     The day names will be localized according to the system's locale
714     settings.
715
716     \sa toString(), shortDayName(), shortMonthName(), longMonthName()
717 */
718
719 QString QDate::longDayName(int weekday, MonthNameType type)
720 {
721     if (weekday < 1 || weekday > 7) {
722         weekday = 1;
723     }
724     switch (type) {
725     case QDate::DateFormat:
726         return QLocale::system().dayName(weekday, QLocale::LongFormat);
727     case QDate::StandaloneFormat:
728         return QLocale::system().standaloneDayName(weekday, QLocale::LongFormat);
729     default:
730         break;
731     }
732     return QLocale::system().dayName(weekday, QLocale::LongFormat);
733 }
734
735 /*!
736     Returns the long version of the name of the \a weekday. The
737     returned name is in normal type which can be used for date formatting.
738
739     \sa toString(), shortDayName(), shortMonthName(), longMonthName()
740  */
741
742 QString QDate::longDayName(int weekday)
743 {
744     if (weekday < 1 || weekday > 7) {
745         weekday = 1;
746     }
747     return QLocale::system().dayName(weekday, QLocale::LongFormat);
748 }
749 #endif //QT_NO_TEXTDATE
750
751 #ifndef QT_NO_DATESTRING
752
753 /*!
754     \fn QString QDate::toString(Qt::DateFormat format) const
755
756     \overload
757
758     Returns the date as a string. The \a format parameter determines
759     the format of the string.
760
761     If the \a format is Qt::TextDate, the string is formatted in
762     the default way. QDate::shortDayName() and QDate::shortMonthName()
763     are used to generate the string, so the day and month names will
764     be localized names. An example of this formatting is
765     "Sat May 20 1995".
766
767     If the \a format is Qt::ISODate, the string format corresponds
768     to the ISO 8601 extended specification for representations of
769     dates and times, taking the form YYYY-MM-DD, where YYYY is the
770     year, MM is the month of the year (between 01 and 12), and DD is
771     the day of the month between 01 and 31.
772
773     If the \a format is Qt::SystemLocaleShortDate or
774     Qt::SystemLocaleLongDate, the string format depends on the locale
775     settings of the system. Identical to calling
776     QLocale::system().toString(date, QLocale::ShortFormat) or
777     QLocale::system().toString(date, QLocale::LongFormat).
778
779     If the \a format is Qt::DefaultLocaleShortDate or
780     Qt::DefaultLocaleLongDate, the string format depends on the
781     default application locale. This is the locale set with
782     QLocale::setDefault(), or the system locale if no default locale
783     has been set. Identical to calling QLocale().toString(date,
784     QLocale::ShortFormat) or QLocale().toString(date,
785     QLocale::LongFormat).
786
787     If the date is invalid, an empty string will be returned.
788
789     \warning The Qt::ISODate format is only valid for years in the
790     range 0 to 9999. This restriction may apply to locale-aware
791     formats as well, depending on the locale settings.
792
793     \sa shortDayName(), shortMonthName()
794 */
795 QString QDate::toString(Qt::DateFormat f) const
796 {
797     if (!isValid())
798         return QString();
799     int y, m, d;
800     getDateFromJulianDay(jd, &y, &m, &d);
801     switch (f) {
802     case Qt::SystemLocaleDate:
803     case Qt::SystemLocaleShortDate:
804     case Qt::SystemLocaleLongDate:
805         return QLocale::system().toString(*this, f == Qt::SystemLocaleLongDate ? QLocale::LongFormat
806                                                                                : QLocale::ShortFormat);
807     case Qt::LocaleDate:
808     case Qt::DefaultLocaleShortDate:
809     case Qt::DefaultLocaleLongDate:
810         return QLocale().toString(*this, f == Qt::DefaultLocaleLongDate ? QLocale::LongFormat
811                                                                         : QLocale::ShortFormat);
812     default:
813 #ifndef QT_NO_TEXTDATE
814     case Qt::TextDate:
815         {
816             return QString::fromLatin1("%0 %1 %2 %3")
817                 .arg(shortDayName(dayOfWeek()))
818                 .arg(shortMonthName(m))
819                 .arg(d)
820                 .arg(y);
821         }
822 #endif
823     case Qt::ISODate:
824         {
825             if (year() < 0 || year() > 9999)
826                 return QString();
827             QString month(QString::number(m).rightJustified(2, QLatin1Char('0')));
828             QString day(QString::number(d).rightJustified(2, QLatin1Char('0')));
829             return QString::number(y) + QLatin1Char('-') + month + QLatin1Char('-') + day;
830         }
831     }
832 }
833
834 /*!
835     Returns the date as a string. The \a format parameter determines
836     the format of the result string.
837
838     These expressions may be used:
839
840     \table
841     \header \i Expression \i Output
842     \row \i d \i the day as number without a leading zero (1 to 31)
843     \row \i dd \i the day as number with a leading zero (01 to 31)
844     \row \i ddd
845          \i the abbreviated localized day name (e.g. 'Mon' to 'Sun').
846             Uses QDate::shortDayName().
847     \row \i dddd
848          \i the long localized day name (e.g. 'Monday' to 'Sunday').
849             Uses QDate::longDayName().
850     \row \i M \i the month as number without a leading zero (1 to 12)
851     \row \i MM \i the month as number with a leading zero (01 to 12)
852     \row \i MMM
853          \i the abbreviated localized month name (e.g. 'Jan' to 'Dec').
854             Uses QDate::shortMonthName().
855     \row \i MMMM
856          \i the long localized month name (e.g. 'January' to 'December').
857             Uses QDate::longMonthName().
858     \row \i yy \i the year as two digit number (00 to 99)
859     \row \i yyyy \i the year as four digit number. If the year is negative,
860             a minus sign is prepended in addition.
861     \endtable
862
863     All other input characters will be ignored. Any sequence of characters that
864     are enclosed in singlequotes will be treated as text and not be used as an
865     expression. Two consecutive singlequotes ("''") are replaced by a singlequote
866     in the output.
867
868     Example format strings (assuming that the QDate is the 20 July
869     1969):
870
871     \table
872     \header \o Format            \o Result
873     \row    \o dd.MM.yyyy        \o 20.07.1969
874     \row    \o ddd MMMM d yy     \o Sun July 20 69
875     \row    \o 'The day is' dddd \o The day is Sunday
876     \endtable
877
878     If the datetime is invalid, an empty string will be returned.
879
880     \warning The Qt::ISODate format is only valid for years in the
881     range 0 to 9999. This restriction may apply to locale-aware
882     formats as well, depending on the locale settings.
883
884     \sa QDateTime::toString() QTime::toString()
885
886 */
887 QString QDate::toString(const QString& format) const
888 {
889     if (year() > 9999)
890         return QString();
891     return fmtDateTime(format, 0, this);
892 }
893 #endif //QT_NO_DATESTRING
894
895 /*!
896     \obsolete
897
898     Sets the date's year \a y, month \a m, and day \a d.
899
900     If \a y is in the range 0 to 99, it is interpreted as 1900 to
901     1999.
902
903     Use setDate() instead.
904 */
905
906 bool QDate::setYMD(int y, int m, int d)
907 {
908     if (uint(y) <= 99)
909         y += 1900;
910     return setDate(y, m, d);
911 }
912
913 /*!
914     \since 4.2
915
916     Sets the date's \a year, \a month, and \a day. Returns true if
917     the date is valid; otherwise returns false.
918
919     If the specified date is invalid, the QDate object is set to be
920     invalid. Any date before 2 January 4713 B.C. is considered
921     invalid.
922
923     \sa isValid()
924 */
925 bool QDate::setDate(int year, int month, int day)
926 {
927     if (!isValid(year, month, day)) {
928         jd = 0;
929     } else {
930         jd = julianDayFromDate(year, month, day);
931     }
932     return jd != 0;
933 }
934
935 /*!
936     \since 4.5
937
938     Extracts the date's year, month, and day, and assigns them to
939     *\a year, *\a month, and *\a day. The pointers may be null.
940
941     \sa year(), month(), day(), isValid()
942 */
943 void QDate::getDate(int *year, int *month, int *day)
944 {
945     getDateFromJulianDay(jd, year, month, day);
946 }
947
948 /*!
949     Returns a QDate object containing a date \a ndays later than the
950     date of this object (or earlier if \a ndays is negative).
951
952     \sa addMonths() addYears() daysTo()
953 */
954
955 QDate QDate::addDays(int ndays) const
956 {
957     QDate d;
958     // this is basically "d.jd = jd + ndays" with checks for integer overflow
959     if (ndays >= 0)
960         d.jd = (jd + ndays >= jd) ? jd + ndays : 0;
961     else
962         d.jd = (jd + ndays < jd) ? jd + ndays : 0;
963     return d;
964 }
965
966 /*!
967     Returns a QDate object containing a date \a nmonths later than the
968     date of this object (or earlier if \a nmonths is negative).
969
970     \note If the ending day/month combination does not exist in the
971     resulting month/year, this function will return a date that is the
972     latest valid date.
973
974     \warning QDate has a date hole around the days introducing the
975     Gregorian calendar (the days 5 to 14 October 1582, inclusive, do
976     not exist). If the calculation ends in one of those days, QDate
977     will return either October 4 or October 15.
978
979     \sa addDays() addYears()
980 */
981
982 QDate QDate::addMonths(int nmonths) const
983 {
984     if (!isValid())
985         return QDate();
986     if (!nmonths)
987         return *this;
988
989     int old_y, y, m, d;
990     getDateFromJulianDay(jd, &y, &m, &d);
991     old_y = y;
992
993     bool increasing = nmonths > 0;
994
995     while (nmonths != 0) {
996         if (nmonths < 0 && nmonths + 12 <= 0) {
997             y--;
998             nmonths+=12;
999         } else if (nmonths < 0) {
1000             m+= nmonths;
1001             nmonths = 0;
1002             if (m <= 0) {
1003                 --y;
1004                 m += 12;
1005             }
1006         } else if (nmonths - 12 >= 0) {
1007             y++;
1008             nmonths -= 12;
1009         } else if (m == 12) {
1010             y++;
1011             m = 0;
1012         } else {
1013             m += nmonths;
1014             nmonths = 0;
1015             if (m > 12) {
1016                 ++y;
1017                 m -= 12;
1018             }
1019         }
1020     }
1021
1022     // was there a sign change?
1023     if ((old_y > 0 && y <= 0) ||
1024         (old_y < 0 && y >= 0))
1025         // yes, adjust the date by +1 or -1 years
1026         y += increasing ? +1 : -1;
1027
1028     // did we end up in the Gregorian/Julian conversion hole?
1029     if (y == 1582 && m == 10 && d > 4 && d < 15)
1030         d = increasing ? 15 : 4;
1031
1032     return fixedDate(y, m, d);
1033 }
1034
1035 /*!
1036     Returns a QDate object containing a date \a nyears later than the
1037     date of this object (or earlier if \a nyears is negative).
1038
1039     \note If the ending day/month combination does not exist in the
1040     resulting year (i.e., if the date was Feb 29 and the final year is
1041     not a leap year), this function will return a date that is the
1042     latest valid date (that is, Feb 28).
1043
1044     \sa addDays(), addMonths()
1045 */
1046
1047 QDate QDate::addYears(int nyears) const
1048 {
1049     if (!isValid())
1050         return QDate();
1051
1052     int y, m, d;
1053     getDateFromJulianDay(jd, &y, &m, &d);
1054
1055     int old_y = y;
1056     y += nyears;
1057
1058     // was there a sign change?
1059     if ((old_y > 0 && y <= 0) ||
1060         (old_y < 0 && y >= 0))
1061         // yes, adjust the date by +1 or -1 years
1062         y += nyears > 0 ? +1 : -1;
1063
1064     return fixedDate(y, m, d);
1065 }
1066
1067 /*!
1068     Returns the number of days from this date to \a d (which is
1069     negative if \a d is earlier than this date).
1070
1071     Example:
1072     \snippet doc/src/snippets/code/src_corelib_tools_qdatetime.cpp 0
1073
1074     \sa addDays()
1075 */
1076
1077 int QDate::daysTo(const QDate &d) const
1078 {
1079     return d.jd - jd;
1080 }
1081
1082
1083 /*!
1084     \fn bool QDate::operator==(const QDate &d) const
1085
1086     Returns true if this date is equal to \a d; otherwise returns
1087     false.
1088
1089 */
1090
1091 /*!
1092     \fn bool QDate::operator!=(const QDate &d) const
1093
1094     Returns true if this date is different from \a d; otherwise
1095     returns false.
1096 */
1097
1098 /*!
1099     \fn bool QDate::operator<(const QDate &d) const
1100
1101     Returns true if this date is earlier than \a d; otherwise returns
1102     false.
1103 */
1104
1105 /*!
1106     \fn bool QDate::operator<=(const QDate &d) const
1107
1108     Returns true if this date is earlier than or equal to \a d;
1109     otherwise returns false.
1110 */
1111
1112 /*!
1113     \fn bool QDate::operator>(const QDate &d) const
1114
1115     Returns true if this date is later than \a d; otherwise returns
1116     false.
1117 */
1118
1119 /*!
1120     \fn bool QDate::operator>=(const QDate &d) const
1121
1122     Returns true if this date is later than or equal to \a d;
1123     otherwise returns false.
1124 */
1125
1126 /*!
1127     \fn QDate::currentDate()
1128     Returns the current date, as reported by the system clock.
1129
1130     \sa QTime::currentTime(), QDateTime::currentDateTime()
1131 */
1132
1133 #ifndef QT_NO_DATESTRING
1134 /*!
1135     \fn QDate QDate::fromString(const QString &string, Qt::DateFormat format)
1136
1137     Returns the QDate represented by the \a string, using the
1138     \a format given, or an invalid date if the string cannot be
1139     parsed.
1140
1141     Note for Qt::TextDate: It is recommended that you use the
1142     English short month names (e.g. "Jan"). Although localized month
1143     names can also be used, they depend on the user's locale settings.
1144 */
1145 QDate QDate::fromString(const QString& s, Qt::DateFormat f)
1146 {
1147     if (s.isEmpty())
1148         return QDate();
1149
1150     switch (f) {
1151     case Qt::ISODate:
1152         {
1153             int year(s.mid(0, 4).toInt());
1154             int month(s.mid(5, 2).toInt());
1155             int day(s.mid(8, 2).toInt());
1156             if (year && month && day)
1157                 return QDate(year, month, day);
1158         }
1159         break;
1160     case Qt::SystemLocaleDate:
1161     case Qt::SystemLocaleShortDate:
1162     case Qt::SystemLocaleLongDate:
1163         return fromString(s, QLocale::system().dateFormat(f == Qt::SystemLocaleLongDate ? QLocale::LongFormat
1164                                                                                         : QLocale::ShortFormat));
1165     case Qt::LocaleDate:
1166     case Qt::DefaultLocaleShortDate:
1167     case Qt::DefaultLocaleLongDate:
1168         return fromString(s, QLocale().dateFormat(f == Qt::DefaultLocaleLongDate ? QLocale::LongFormat
1169                                                                                  : QLocale::ShortFormat));
1170     default:
1171 #ifndef QT_NO_TEXTDATE
1172     case Qt::TextDate: {
1173         QStringList parts = s.split(QLatin1Char(' '), QString::SkipEmptyParts);
1174
1175         if (parts.count() != 4) {
1176             return QDate();
1177         }
1178
1179         QString monthName = parts.at(1);
1180         int month = -1;
1181         // Assume that English monthnames are the default
1182         for (int i = 0; i < 12; ++i) {
1183             if (monthName == QLatin1String(qt_shortMonthNames[i])) {
1184                 month = i + 1;
1185                 break;
1186             }
1187         }
1188         // If English names can't be found, search the localized ones
1189         if (month == -1) {
1190             for (int i = 1; i <= 12; ++i) {
1191                 if (monthName == QDate::shortMonthName(i)) {
1192                     month = i;
1193                     break;
1194                 }
1195             }
1196         }
1197         if (month < 1 || month > 12) {
1198             return QDate();
1199         }
1200
1201         bool ok;
1202         int day = parts.at(2).toInt(&ok);
1203         if (!ok) {
1204             return QDate();
1205         }
1206
1207         int year = parts.at(3).toInt(&ok);
1208         if (!ok) {
1209             return QDate();
1210         }
1211
1212         return QDate(year, month, day);
1213     }
1214 #else
1215         break;
1216 #endif
1217     }
1218     return QDate();
1219 }
1220
1221 /*!
1222     \fn QDate::fromString(const QString &string, const QString &format)
1223
1224     Returns the QDate represented by the \a string, using the \a
1225     format given, or an invalid date if the string cannot be parsed.
1226
1227     These expressions may be used for the format:
1228
1229     \table
1230     \header \i Expression \i Output
1231     \row \i d \i The day as a number without a leading zero (1 to 31)
1232     \row \i dd \i The day as a number with a leading zero (01 to 31)
1233     \row \i ddd
1234          \i The abbreviated localized day name (e.g. 'Mon' to 'Sun').
1235             Uses QDate::shortDayName().
1236     \row \i dddd
1237          \i The long localized day name (e.g. 'Monday' to 'Sunday').
1238             Uses QDate::longDayName().
1239     \row \i M \i The month as a number without a leading zero (1 to 12)
1240     \row \i MM \i The month as a number with a leading zero (01 to 12)
1241     \row \i MMM
1242          \i The abbreviated localized month name (e.g. 'Jan' to 'Dec').
1243             Uses QDate::shortMonthName().
1244     \row \i MMMM
1245          \i The long localized month name (e.g. 'January' to 'December').
1246             Uses QDate::longMonthName().
1247     \row \i yy \i The year as two digit number (00 to 99)
1248     \row \i yyyy \i The year as four digit number. If the year is negative,
1249             a minus sign is prepended in addition.
1250     \endtable
1251
1252     All other input characters will be treated as text. Any sequence
1253     of characters that are enclosed in single quotes will also be
1254     treated as text and will not be used as an expression. For example:
1255
1256     \snippet doc/src/snippets/code/src_corelib_tools_qdatetime.cpp 1
1257
1258     If the format is not satisfied, an invalid QDate is returned. The
1259     expressions that don't expect leading zeroes (d, M) will be
1260     greedy. This means that they will use two digits even if this
1261     will put them outside the accepted range of values and leaves too
1262     few digits for other sections. For example, the following format
1263     string could have meant January 30 but the M will grab two
1264     digits, resulting in an invalid date:
1265
1266     \snippet doc/src/snippets/code/src_corelib_tools_qdatetime.cpp 2
1267
1268     For any field that is not represented in the format the following
1269     defaults are used:
1270
1271     \table
1272     \header \i Field  \i Default value
1273     \row    \i Year   \i 1900
1274     \row    \i Month  \i 1
1275     \row    \i Day    \i 1
1276     \endtable
1277
1278     The following examples demonstrate the default values:
1279
1280     \snippet doc/src/snippets/code/src_corelib_tools_qdatetime.cpp 3
1281
1282     \sa QDateTime::fromString(), QTime::fromString(), QDate::toString(),
1283         QDateTime::toString(), QTime::toString()
1284 */
1285
1286 QDate QDate::fromString(const QString &string, const QString &format)
1287 {
1288     QDate date;
1289 #ifndef QT_BOOTSTRAPPED
1290     QDateTimeParser dt(QVariant::Date, QDateTimeParser::FromString);
1291     if (dt.parseFormat(format))
1292         dt.fromString(string, &date, 0);
1293 #else
1294     Q_UNUSED(string);
1295     Q_UNUSED(format);
1296 #endif
1297     return date;
1298 }
1299 #endif // QT_NO_DATESTRING
1300
1301 /*!
1302     \overload
1303
1304     Returns true if the specified date (\a year, \a month, and \a
1305     day) is valid; otherwise returns false.
1306
1307     Example:
1308     \snippet doc/src/snippets/code/src_corelib_tools_qdatetime.cpp 4
1309
1310     \sa isNull(), setDate()
1311 */
1312
1313 bool QDate::isValid(int year, int month, int day)
1314 {
1315     if (year < FIRST_YEAR
1316         || (year == FIRST_YEAR &&
1317             (month < FIRST_MONTH
1318              || (month == FIRST_MONTH && day < FIRST_DAY)))
1319         || year == 0) // there is no year 0 in the Julian calendar
1320         return false;
1321
1322     // passage from Julian to Gregorian calendar
1323     if (year == 1582 && month == 10 && day > 4 && day < 15)
1324         return 0;
1325
1326     return (day > 0 && month > 0 && month <= 12) &&
1327            (day <= monthDays[month] || (day == 29 && month == 2 && isLeapYear(year)));
1328 }
1329
1330 /*!
1331     \fn bool QDate::isLeapYear(int year)
1332
1333     Returns true if the specified \a year is a leap year; otherwise
1334     returns false.
1335 */
1336
1337 bool QDate::isLeapYear(int y)
1338 {
1339     if (y < 1582) {
1340         if ( y < 1) {  // No year 0 in Julian calendar, so -1, -5, -9 etc are leap years
1341             ++y;
1342         }
1343         return y % 4 == 0;
1344     } else {
1345         return (y % 4 == 0 && y % 100 != 0) || y % 400 == 0;
1346     }
1347 }
1348
1349 /*!
1350     \internal
1351
1352     This function has a confusing name and shouldn't be part of the
1353     API anyway, since we have toJulian() and fromJulian().
1354     ### Qt 5: remove it
1355 */
1356 uint QDate::gregorianToJulian(int y, int m, int d)
1357 {
1358     return julianDayFromDate(y, m, d);
1359 }
1360
1361 /*!
1362     \internal
1363
1364     This function has a confusing name and shouldn't be part of the
1365     API anyway, since we have toJulian() and fromJulian().
1366     ### Qt 5: remove it
1367 */
1368 void QDate::julianToGregorian(uint jd, int &y, int &m, int &d)
1369 {
1370     getDateFromJulianDay(jd, &y, &m, &d);
1371 }
1372
1373 /*! \fn static QDate QDate::fromJulianDay(int jd)
1374
1375     Converts the Julian day \a jd to a QDate.
1376
1377     \sa toJulianDay()
1378 */
1379
1380 /*! \fn int QDate::toJulianDay() const
1381
1382     Converts the date to a Julian day.
1383
1384     \sa fromJulianDay()
1385 */
1386
1387 /*****************************************************************************
1388   QTime member functions
1389  *****************************************************************************/
1390
1391 /*!
1392     \class QTime
1393     \reentrant
1394
1395     \brief The QTime class provides clock time functions.
1396
1397
1398     A QTime object contains a clock time, i.e. the number of hours,
1399     minutes, seconds, and milliseconds since midnight. It can read the
1400     current time from the system clock and measure a span of elapsed
1401     time. It provides functions for comparing times and for
1402     manipulating a time by adding a number of milliseconds.
1403
1404     QTime uses the 24-hour clock format; it has no concept of AM/PM.
1405     Unlike QDateTime, QTime knows nothing about time zones or
1406     daylight savings time (DST).
1407
1408     A QTime object is typically created either by giving the number
1409     of hours, minutes, seconds, and milliseconds explicitly, or by
1410     using the static function currentTime(), which creates a QTime
1411     object that contains the system's local time. Note that the
1412     accuracy depends on the accuracy of the underlying operating
1413     system; not all systems provide 1-millisecond accuracy.
1414
1415     The hour(), minute(), second(), and msec() functions provide
1416     access to the number of hours, minutes, seconds, and milliseconds
1417     of the time. The same information is provided in textual format by
1418     the toString() function.
1419
1420     QTime provides a full set of operators to compare two QTime
1421     objects. One time is considered smaller than another if it is
1422     earlier than the other.
1423
1424     The time a given number of seconds or milliseconds later than a
1425     given time can be found using the addSecs() or addMSecs()
1426     functions. Correspondingly, the number of seconds or milliseconds
1427     between two times can be found using secsTo() or msecsTo().
1428
1429     QTime can be used to measure a span of elapsed time using the
1430     start(), restart(), and elapsed() functions.
1431
1432     \sa QDate, QDateTime
1433 */
1434
1435 /*!
1436     \fn QTime::QTime()
1437
1438     Constructs a null time object. A null time can be a QTime(0, 0, 0, 0)
1439     (i.e., midnight) object, except that isNull() returns true and isValid()
1440     returns false.
1441
1442     \sa isNull(), isValid()
1443 */
1444
1445 /*!
1446     Constructs a time with hour \a h, minute \a m, seconds \a s and
1447     milliseconds \a ms.
1448
1449     \a h must be in the range 0 to 23, \a m and \a s must be in the
1450     range 0 to 59, and \a ms must be in the range 0 to 999.
1451
1452     \sa isValid()
1453 */
1454
1455 QTime::QTime(int h, int m, int s, int ms)
1456 {
1457     setHMS(h, m, s, ms);
1458 }
1459
1460
1461 /*!
1462     \fn bool QTime::isNull() const
1463
1464     Returns true if the time is null (i.e., the QTime object was
1465     constructed using the default constructor); otherwise returns
1466     false. A null time is also an invalid time.
1467
1468     \sa isValid()
1469 */
1470
1471 /*!
1472     Returns true if the time is valid; otherwise returns false. For example,
1473     the time 23:30:55.746 is valid, but 24:12:30 is invalid.
1474
1475     \sa isNull()
1476 */
1477
1478 bool QTime::isValid() const
1479 {
1480     return mds > NullTime && mds < MSECS_PER_DAY;
1481 }
1482
1483
1484 /*!
1485     Returns the hour part (0 to 23) of the time.
1486
1487     \sa minute(), second(), msec()
1488 */
1489
1490 int QTime::hour() const
1491 {
1492     return ds() / MSECS_PER_HOUR;
1493 }
1494
1495 /*!
1496     Returns the minute part (0 to 59) of the time.
1497
1498     \sa hour(), second(), msec()
1499 */
1500
1501 int QTime::minute() const
1502 {
1503     return (ds() % MSECS_PER_HOUR) / MSECS_PER_MIN;
1504 }
1505
1506 /*!
1507     Returns the second part (0 to 59) of the time.
1508
1509     \sa hour(), minute(), msec()
1510 */
1511
1512 int QTime::second() const
1513 {
1514     return (ds() / 1000)%SECS_PER_MIN;
1515 }
1516
1517 /*!
1518     Returns the millisecond part (0 to 999) of the time.
1519
1520     \sa hour(), minute(), second()
1521 */
1522
1523 int QTime::msec() const
1524 {
1525     return ds() % 1000;
1526 }
1527
1528 #ifndef QT_NO_DATESTRING
1529 /*!
1530     \overload
1531
1532     Returns the time as a string. Milliseconds are not included. The
1533     \a format parameter determines the format of the string.
1534
1535     If \a format is Qt::TextDate, the string format is HH:MM:SS; e.g. 1
1536     second before midnight would be "23:59:59".
1537
1538     If \a format is Qt::ISODate, the string format corresponds to the
1539     ISO 8601 extended specification for representations of dates,
1540     which is also HH:MM:SS. (However, contrary to ISO 8601, dates
1541     before 15 October 1582 are handled as Julian dates, not Gregorian
1542     dates. See \l{QDate G and J} {Use of Gregorian and Julian
1543     Calendars}. This might change in a future version of Qt.)
1544
1545     If the \a format is Qt::SystemLocaleShortDate or
1546     Qt::SystemLocaleLongDate, the string format depends on the locale
1547     settings of the system. Identical to calling
1548     QLocale::system().toString(time, QLocale::ShortFormat) or
1549     QLocale::system().toString(time, QLocale::LongFormat).
1550
1551     If the \a format is Qt::DefaultLocaleShortDate or
1552     Qt::DefaultLocaleLongDate, the string format depends on the
1553     default application locale. This is the locale set with
1554     QLocale::setDefault(), or the system locale if no default locale
1555     has been set. Identical to calling QLocale().toString(time,
1556     QLocale::ShortFormat) or QLocale().toString(time,
1557     QLocale::LongFormat).
1558
1559     If the time is invalid, an empty string will be returned.
1560 */
1561
1562 QString QTime::toString(Qt::DateFormat format) const
1563 {
1564     if (!isValid())
1565         return QString();
1566
1567     switch (format) {
1568     case Qt::SystemLocaleDate:
1569     case Qt::SystemLocaleShortDate:
1570     case Qt::SystemLocaleLongDate:
1571         return QLocale::system().toString(*this, format == Qt::SystemLocaleLongDate ? QLocale::LongFormat
1572                                           : QLocale::ShortFormat);
1573     case Qt::LocaleDate:
1574     case Qt::DefaultLocaleShortDate:
1575     case Qt::DefaultLocaleLongDate:
1576         return QLocale().toString(*this, format == Qt::DefaultLocaleLongDate ? QLocale::LongFormat
1577                                   : QLocale::ShortFormat);
1578
1579     default:
1580     case Qt::ISODate:
1581     case Qt::TextDate:
1582         return QString::fromLatin1("%1:%2:%3")
1583             .arg(hour(), 2, 10, QLatin1Char('0'))
1584             .arg(minute(), 2, 10, QLatin1Char('0'))
1585             .arg(second(), 2, 10, QLatin1Char('0'));
1586     }
1587 }
1588
1589 /*!
1590     Returns the time as a string. The \a format parameter determines
1591     the format of the result string.
1592
1593     These expressions may be used:
1594
1595     \table
1596     \header \i Expression \i Output
1597     \row \i h
1598          \i the hour without a leading zero (0 to 23 or 1 to 12 if AM/PM display)
1599     \row \i hh
1600          \i the hour with a leading zero (00 to 23 or 01 to 12 if AM/PM display)
1601     \row \i H
1602          \i the hour without a leading zero (0 to 23, even with AM/PM display)
1603     \row \i HH
1604          \i the hour with a leading zero (00 to 23, even with AM/PM display)
1605     \row \i m \i the minute without a leading zero (0 to 59)
1606     \row \i mm \i the minute with a leading zero (00 to 59)
1607     \row \i s \i the second without a leading zero (0 to 59)
1608     \row \i ss \i the second with a leading zero (00 to 59)
1609     \row \i z \i the milliseconds without leading zeroes (0 to 999)
1610     \row \i zzz \i the milliseconds with leading zeroes (000 to 999)
1611     \row \i AP or A
1612          \i use AM/PM display. \e AP will be replaced by either "AM" or "PM".
1613     \row \i ap or a
1614          \i use am/pm display. \e ap will be replaced by either "am" or "pm".
1615     \row \i t \i the timezone (for example "CEST")
1616     \endtable
1617
1618     All other input characters will be ignored. Any sequence of characters that
1619     are enclosed in singlequotes will be treated as text and not be used as an
1620     expression. Two consecutive singlequotes ("''") are replaced by a singlequote
1621     in the output.
1622
1623     Example format strings (assuming that the QTime is 14:13:09.042)
1624
1625     \table
1626     \header \i Format \i Result
1627     \row \i hh:mm:ss.zzz \i 14:13:09.042
1628     \row \i h:m:s ap     \i 2:13:9 pm
1629     \row \i H:m:s a      \i 14:13:9 pm
1630     \endtable
1631
1632     If the datetime is invalid, an empty string will be returned.
1633     If \a format is empty, the default format "hh:mm:ss" is used.
1634
1635     \sa QDate::toString() QDateTime::toString()
1636 */
1637 QString QTime::toString(const QString& format) const
1638 {
1639     return fmtDateTime(format, this, 0);
1640 }
1641 #endif //QT_NO_DATESTRING
1642 /*!
1643     Sets the time to hour \a h, minute \a m, seconds \a s and
1644     milliseconds \a ms.
1645
1646     \a h must be in the range 0 to 23, \a m and \a s must be in the
1647     range 0 to 59, and \a ms must be in the range 0 to 999.
1648     Returns true if the set time is valid; otherwise returns false.
1649
1650     \sa isValid()
1651 */
1652
1653 bool QTime::setHMS(int h, int m, int s, int ms)
1654 {
1655 #if defined(Q_OS_WINCE)
1656     startTick = NullTime;
1657 #endif
1658     if (!isValid(h,m,s,ms)) {
1659         mds = NullTime;                // make this invalid
1660         return false;
1661     }
1662     mds = (h*SECS_PER_HOUR + m*SECS_PER_MIN + s)*1000 + ms;
1663     return true;
1664 }
1665
1666 /*!
1667     Returns a QTime object containing a time \a s seconds later
1668     than the time of this object (or earlier if \a s is negative).
1669
1670     Note that the time will wrap if it passes midnight.
1671
1672     Example:
1673
1674     \snippet doc/src/snippets/code/src_corelib_tools_qdatetime.cpp 5
1675
1676     \sa addMSecs(), secsTo(), QDateTime::addSecs()
1677 */
1678
1679 QTime QTime::addSecs(int s) const
1680 {
1681     return addMSecs(s * 1000);
1682 }
1683
1684 /*!
1685     Returns the number of seconds from this time to \a t.
1686     If \a t is earlier than this time, the number of seconds returned
1687     is negative.
1688
1689     Because QTime measures time within a day and there are 86400
1690     seconds in a day, the result is always between -86400 and 86400.
1691
1692     secsTo() does not take into account any milliseconds.
1693
1694     \sa addSecs(), QDateTime::secsTo()
1695 */
1696
1697 int QTime::secsTo(const QTime &t) const
1698 {
1699     return (t.ds() - ds()) / 1000;
1700 }
1701
1702 /*!
1703     Returns a QTime object containing a time \a ms milliseconds later
1704     than the time of this object (or earlier if \a ms is negative).
1705
1706     Note that the time will wrap if it passes midnight. See addSecs()
1707     for an example.
1708
1709     \sa addSecs(), msecsTo(), QDateTime::addMSecs()
1710 */
1711
1712 QTime QTime::addMSecs(int ms) const
1713 {
1714     QTime t;
1715     if (ms < 0) {
1716         // % not well-defined for -ve, but / is.
1717         int negdays = (MSECS_PER_DAY - ms) / MSECS_PER_DAY;
1718         t.mds = (ds() + ms + negdays * MSECS_PER_DAY) % MSECS_PER_DAY;
1719     } else {
1720         t.mds = (ds() + ms) % MSECS_PER_DAY;
1721     }
1722 #if defined(Q_OS_WINCE)
1723     if (startTick > NullTime)
1724         t.startTick = (startTick + ms) % MSECS_PER_DAY;
1725 #endif
1726     return t;
1727 }
1728
1729 /*!
1730     Returns the number of milliseconds from this time to \a t.
1731     If \a t is earlier than this time, the number of milliseconds returned
1732     is negative.
1733
1734     Because QTime measures time within a day and there are 86400
1735     seconds in a day, the result is always between -86400000 and
1736     86400000 ms.
1737
1738     \sa secsTo(), addMSecs(), QDateTime::msecsTo()
1739 */
1740
1741 int QTime::msecsTo(const QTime &t) const
1742 {
1743 #if defined(Q_OS_WINCE)
1744     // GetLocalTime() for Windows CE has no milliseconds resolution
1745     if (t.startTick > NullTime && startTick > NullTime)
1746         return t.startTick - startTick;
1747     else
1748 #endif
1749         return t.ds() - ds();
1750 }
1751
1752
1753 /*!
1754     \fn bool QTime::operator==(const QTime &t) const
1755
1756     Returns true if this time is equal to \a t; otherwise returns false.
1757 */
1758
1759 /*!
1760     \fn bool QTime::operator!=(const QTime &t) const
1761
1762     Returns true if this time is different from \a t; otherwise returns false.
1763 */
1764
1765 /*!
1766     \fn bool QTime::operator<(const QTime &t) const
1767
1768     Returns true if this time is earlier than \a t; otherwise returns false.
1769 */
1770
1771 /*!
1772     \fn bool QTime::operator<=(const QTime &t) const
1773
1774     Returns true if this time is earlier than or equal to \a t;
1775     otherwise returns false.
1776 */
1777
1778 /*!
1779     \fn bool QTime::operator>(const QTime &t) const
1780
1781     Returns true if this time is later than \a t; otherwise returns false.
1782 */
1783
1784 /*!
1785     \fn bool QTime::operator>=(const QTime &t) const
1786
1787     Returns true if this time is later than or equal to \a t;
1788     otherwise returns false.
1789 */
1790
1791 /*!
1792     \fn QTime::currentTime()
1793
1794     Returns the current time as reported by the system clock.
1795
1796     Note that the accuracy depends on the accuracy of the underlying
1797     operating system; not all systems provide 1-millisecond accuracy.
1798 */
1799
1800 #ifndef QT_NO_DATESTRING
1801 /*!
1802     \fn QTime QTime::fromString(const QString &string, Qt::DateFormat format)
1803
1804     Returns the time represented in the \a string as a QTime using the
1805     \a format given, or an invalid time if this is not possible.
1806
1807     Note that fromString() uses a "C" locale encoded string to convert
1808     milliseconds to a float value. If the default locale is not "C",
1809     this may result in two conversion attempts (if the conversion
1810     fails for the default locale). This should be considered an
1811     implementation detail.
1812 */
1813 QTime QTime::fromString(const QString& s, Qt::DateFormat f)
1814 {
1815     if (s.isEmpty()) {
1816         QTime t;
1817         t.mds = NullTime;
1818         return t;
1819     }
1820
1821     switch (f) {
1822     case Qt::SystemLocaleDate:
1823     case Qt::SystemLocaleShortDate:
1824     case Qt::SystemLocaleLongDate:
1825         return fromString(s, QLocale::system().timeFormat(f == Qt::SystemLocaleLongDate ? QLocale::LongFormat
1826                                                                                         : QLocale::ShortFormat));
1827     case Qt::LocaleDate:
1828     case Qt::DefaultLocaleShortDate:
1829     case Qt::DefaultLocaleLongDate:
1830         return fromString(s, QLocale().timeFormat(f == Qt::DefaultLocaleLongDate ? QLocale::LongFormat
1831                                                                                  : QLocale::ShortFormat));
1832     default:
1833         {
1834             bool ok = true;
1835             const int hour(s.mid(0, 2).toInt(&ok));
1836             if (!ok)
1837                 return QTime();
1838             const int minute(s.mid(3, 2).toInt(&ok));
1839             if (!ok)
1840                 return QTime();
1841             const int second(s.mid(6, 2).toInt(&ok));
1842             if (!ok)
1843                 return QTime();
1844             const QString msec_s(QLatin1String("0.") + s.mid(9, 4));
1845             const float msec(msec_s.toFloat(&ok));
1846             if (!ok)
1847                 return QTime(hour, minute, second, 0);
1848             return QTime(hour, minute, second, qMin(qRound(msec * 1000.0), 999));
1849         }
1850     }
1851 }
1852
1853 /*!
1854     \fn QTime::fromString(const QString &string, const QString &format)
1855
1856     Returns the QTime represented by the \a string, using the \a
1857     format given, or an invalid time if the string cannot be parsed.
1858
1859     These expressions may be used for the format:
1860
1861     \table
1862     \header \i Expression \i Output
1863     \row \i h
1864          \i the hour without a leading zero (0 to 23 or 1 to 12 if AM/PM display)
1865     \row \i hh
1866          \i the hour with a leading zero (00 to 23 or 01 to 12 if AM/PM display)
1867     \row \i m \i the minute without a leading zero (0 to 59)
1868     \row \i mm \i the minute with a leading zero (00 to 59)
1869     \row \i s \i the second without a leading zero (0 to 59)
1870     \row \i ss \i the second with a leading zero (00 to 59)
1871     \row \i z \i the milliseconds without leading zeroes (0 to 999)
1872     \row \i zzz \i the milliseconds with leading zeroes (000 to 999)
1873     \row \i AP
1874          \i interpret as an AM/PM time. \e AP must be either "AM" or "PM".
1875     \row \i ap
1876          \i Interpret as an AM/PM time. \e ap must be either "am" or "pm".
1877     \endtable
1878
1879     All other input characters will be treated as text. Any sequence
1880     of characters that are enclosed in single quotes will also be
1881     treated as text and not be used as an expression.
1882
1883     \snippet doc/src/snippets/code/src_corelib_tools_qdatetime.cpp 6
1884
1885     If the format is not satisfied an invalid QTime is returned.
1886     Expressions that do not expect leading zeroes to be given (h, m, s
1887     and z) are greedy. This means that they will use two digits even if
1888     this puts them outside the range of accepted values and leaves too
1889     few digits for other sections. For example, the following string
1890     could have meant 00:07:10, but the m will grab two digits, resulting
1891     in an invalid time:
1892
1893     \snippet doc/src/snippets/code/src_corelib_tools_qdatetime.cpp 7
1894
1895     Any field that is not represented in the format will be set to zero.
1896     For example:
1897
1898     \snippet doc/src/snippets/code/src_corelib_tools_qdatetime.cpp 8
1899
1900     \sa QDateTime::fromString() QDate::fromString() QDate::toString()
1901     QDateTime::toString() QTime::toString()
1902 */
1903
1904 QTime QTime::fromString(const QString &string, const QString &format)
1905 {
1906     QTime time;
1907 #ifndef QT_BOOTSTRAPPED
1908     QDateTimeParser dt(QVariant::Time, QDateTimeParser::FromString);
1909     if (dt.parseFormat(format))
1910         dt.fromString(string, 0, &time);
1911 #else
1912     Q_UNUSED(string);
1913     Q_UNUSED(format);
1914 #endif
1915     return time;
1916 }
1917
1918 #endif // QT_NO_DATESTRING
1919
1920
1921 /*!
1922     \overload
1923
1924     Returns true if the specified time is valid; otherwise returns
1925     false.
1926
1927     The time is valid if \a h is in the range 0 to 23, \a m and
1928     \a s are in the range 0 to 59, and \a ms is in the range 0 to 999.
1929
1930     Example:
1931
1932     \snippet doc/src/snippets/code/src_corelib_tools_qdatetime.cpp 9
1933 */
1934
1935 bool QTime::isValid(int h, int m, int s, int ms)
1936 {
1937     return (uint)h < 24 && (uint)m < 60 && (uint)s < 60 && (uint)ms < 1000;
1938 }
1939
1940
1941 /*!
1942     Sets this time to the current time. This is practical for timing:
1943
1944     \snippet doc/src/snippets/code/src_corelib_tools_qdatetime.cpp 10
1945
1946     \sa restart(), elapsed(), currentTime()
1947 */
1948
1949 void QTime::start()
1950 {
1951     *this = currentTime();
1952 }
1953
1954 /*!
1955     Sets this time to the current time and returns the number of
1956     milliseconds that have elapsed since the last time start() or
1957     restart() was called.
1958
1959     This function is guaranteed to be atomic and is thus very handy
1960     for repeated measurements. Call start() to start the first
1961     measurement, and restart() for each later measurement.
1962
1963     Note that the counter wraps to zero 24 hours after the last call
1964     to start() or restart().
1965
1966     \warning If the system's clock setting has been changed since the
1967     last time start() or restart() was called, the result is
1968     undefined. This can happen when daylight savings time is turned on
1969     or off.
1970
1971     \sa start(), elapsed(), currentTime()
1972 */
1973
1974 int QTime::restart()
1975 {
1976     QTime t = currentTime();
1977     int n = msecsTo(t);
1978     if (n < 0)                                // passed midnight
1979         n += 86400*1000;
1980     *this = t;
1981     return n;
1982 }
1983
1984 /*!
1985     Returns the number of milliseconds that have elapsed since the
1986     last time start() or restart() was called.
1987
1988     Note that the counter wraps to zero 24 hours after the last call
1989     to start() or restart.
1990
1991     Note that the accuracy depends on the accuracy of the underlying
1992     operating system; not all systems provide 1-millisecond accuracy.
1993
1994     \warning If the system's clock setting has been changed since the
1995     last time start() or restart() was called, the result is
1996     undefined. This can happen when daylight savings time is turned on
1997     or off.
1998
1999     \sa start(), restart()
2000 */
2001
2002 int QTime::elapsed() const
2003 {
2004     int n = msecsTo(currentTime());
2005     if (n < 0)                                // passed midnight
2006         n += 86400 * 1000;
2007     return n;
2008 }
2009
2010
2011 /*****************************************************************************
2012   QDateTime member functions
2013  *****************************************************************************/
2014
2015 /*!
2016     \class QDateTime
2017     \reentrant
2018     \brief The QDateTime class provides date and time functions.
2019
2020
2021     A QDateTime object contains a calendar date and a clock time (a
2022     "datetime"). It is a combination of the QDate and QTime classes.
2023     It can read the current datetime from the system clock. It
2024     provides functions for comparing datetimes and for manipulating a
2025     datetime by adding a number of seconds, days, months, or years.
2026
2027     A QDateTime object is typically created either by giving a date
2028     and time explicitly in the constructor, or by using the static
2029     function currentDateTime() that returns a QDateTime object set
2030     to the system clock's time. The date and time can be changed with
2031     setDate() and setTime(). A datetime can also be set using the
2032     setTime_t() function that takes a POSIX-standard "number of
2033     seconds since 00:00:00 on January 1, 1970" value. The fromString()
2034     function returns a QDateTime, given a string and a date format
2035     used to interpret the date within the string.
2036
2037     The date() and time() functions provide access to the date and
2038     time parts of the datetime. The same information is provided in
2039     textual format by the toString() function.
2040
2041     QDateTime provides a full set of operators to compare two
2042     QDateTime objects where smaller means earlier and larger means
2043     later.
2044
2045     You can increment (or decrement) a datetime by a given number of
2046     milliseconds using addMSecs(), seconds using addSecs(), or days
2047     using addDays(). Similarly you can use addMonths() and addYears().
2048     The daysTo() function returns the number of days between two datetimes,
2049     secsTo() returns the number of seconds between two datetimes, and
2050     msecsTo() returns the number of milliseconds between two datetimes.
2051
2052     QDateTime can store datetimes as \l{Qt::LocalTime}{local time} or
2053     as \l{Qt::UTC}{UTC}. QDateTime::currentDateTime() returns a
2054     QDateTime expressed as local time; use toUTC() to convert it to
2055     UTC. You can also use timeSpec() to find out if a QDateTime
2056     object stores a UTC time or a local time. Operations such as
2057     addSecs() and secsTo() are aware of daylight saving time (DST).
2058
2059     \note QDateTime does not account for leap seconds.
2060
2061     \section1
2062
2063     \target QDateTime G and J
2064     \section2 Use of Gregorian and Julian Calendars
2065
2066     QDate uses the Gregorian calendar in all locales, beginning
2067     on the date 15 October 1582. For dates up to and including 4
2068     October 1582, the Julian calendar is used.  This means there is a
2069     10-day gap in the internal calendar between the 4th and the 15th
2070     of October 1582. When you use QDateTime for dates in that epoch,
2071     the day after 4 October 1582 is 15 October 1582, and the dates in
2072     the gap are invalid.
2073
2074     The Julian to Gregorian changeover date used here is the date when
2075     the Gregorian calendar was first introduced, by Pope Gregory
2076     XIII. That change was not universally accepted and some localities
2077     only executed it at a later date (if at all).  QDateTime
2078     doesn't take any of these historical facts into account. If an
2079     application must support a locale-specific dating system, it must
2080     do so on its own, remembering to convert the dates using the
2081     Julian day.
2082
2083     \section2 No Year 0
2084
2085     There is no year 0. Dates in that year are considered invalid. The
2086     year -1 is the year "1 before Christ" or "1 before current era."
2087     The day before 0001-01-01 is December 31st, 1 BCE.
2088
2089     \section2 Range of Valid Dates
2090
2091     The range of valid dates is from January 2nd, 4713 BCE, to
2092     sometime in the year 11 million CE. The Julian Day returned by
2093     QDate::toJulianDay() is a number in the contiguous range from 1 to
2094     \e{overflow}, even across QDateTime's "date holes". It is suitable
2095     for use in applications that must convert a QDateTime to a date in
2096     another calendar system, e.g., Hebrew, Islamic or Chinese.
2097
2098     The Gregorian calendar was introduced in different places around
2099     the world on different dates. QDateTime uses QDate to store the
2100     date, so it uses the Gregorian calendar for all locales, beginning
2101     on the date 15 October 1582. For dates up to and including 4
2102     October 1582, QDateTime uses the Julian calendar.  This means
2103     there is a 10-day gap in the QDateTime calendar between the 4th
2104     and the 15th of October 1582. When you use QDateTime for dates in
2105     that epoch, the day after 4 October 1582 is 15 October 1582, and
2106     the dates in the gap are invalid.
2107
2108     \section2
2109     Use of System Timezone
2110
2111     QDateTime uses the system's time zone information to determine the
2112     offset of local time from UTC. If the system is not configured
2113     correctly or not up-to-date, QDateTime will give wrong results as
2114     well.
2115
2116     \section2 Daylight Savings Time (DST)
2117
2118     QDateTime takes into account the system's time zone information
2119     when dealing with DST. On modern Unix systems, this means it
2120     applies the correct historical DST data whenever possible. On
2121     Windows and Windows CE, where the system doesn't support
2122     historical DST data, historical accuracy is not maintained with
2123     respect to DST.
2124
2125     The range of valid dates taking DST into account is 1970-01-01 to
2126     the present, and rules are in place for handling DST correctly
2127     until 2037-12-31, but these could change. For dates falling
2128     outside that range, QDateTime makes a \e{best guess} using the
2129     rules for year 1970 or 2037, but we can't guarantee accuracy. This
2130     means QDateTime doesn't take into account changes in a locale's
2131     time zone before 1970, even if the system's time zone database
2132     supports that information.
2133
2134     \sa QDate QTime QDateTimeEdit
2135 */
2136
2137 /*!
2138     Constructs a null datetime (i.e. null date and null time). A null
2139     datetime is invalid, since the date is invalid.
2140
2141     \sa isValid()
2142 */
2143 QDateTime::QDateTime()
2144     : d(new QDateTimePrivate)
2145 {
2146 }
2147
2148
2149 /*!
2150     Constructs a datetime with the given \a date, a valid
2151     time(00:00:00.000), and sets the timeSpec() to Qt::LocalTime.
2152 */
2153
2154 QDateTime::QDateTime(const QDate &date)
2155     : d(new QDateTimePrivate)
2156 {
2157     d->date = date;
2158     d->time = QTime(0, 0, 0);
2159 }
2160
2161 /*!
2162     Constructs a datetime with the given \a date and \a time, using
2163     the time specification defined by \a spec.
2164
2165     If \a date is valid and \a time is not, the time will be set to midnight.
2166 */
2167
2168 QDateTime::QDateTime(const QDate &date, const QTime &time, Qt::TimeSpec spec)
2169     : d(new QDateTimePrivate)
2170 {
2171     d->date = date;
2172     d->time = date.isValid() && !time.isValid() ? QTime(0, 0, 0) : time;
2173     d->spec = (spec == Qt::UTC) ? QDateTimePrivate::UTC : QDateTimePrivate::LocalUnknown;
2174 }
2175
2176 /*!
2177     Constructs a copy of the \a other datetime.
2178 */
2179
2180 QDateTime::QDateTime(const QDateTime &other)
2181     : d(other.d)
2182 {
2183 }
2184
2185 /*!
2186     Destroys the datetime.
2187 */
2188 QDateTime::~QDateTime()
2189 {
2190 }
2191
2192 /*!
2193     Makes a copy of the \a other datetime and returns a reference to the
2194     copy.
2195 */
2196
2197 QDateTime &QDateTime::operator=(const QDateTime &other)
2198 {
2199     d = other.d;
2200     return *this;
2201 }
2202
2203 /*!
2204     Returns true if both the date and the time are null; otherwise
2205     returns false. A null datetime is invalid.
2206
2207     \sa QDate::isNull(), QTime::isNull(), isValid()
2208 */
2209
2210 bool QDateTime::isNull() const
2211 {
2212     return d->date.isNull() && d->time.isNull();
2213 }
2214
2215 /*!
2216     Returns true if both the date and the time are valid; otherwise
2217     returns false.
2218
2219     \sa QDate::isValid(), QTime::isValid()
2220 */
2221
2222 bool QDateTime::isValid() const
2223 {
2224     return d->date.isValid() && d->time.isValid();
2225 }
2226
2227 /*!
2228     Returns the date part of the datetime.
2229
2230     \sa setDate(), time(), timeSpec()
2231 */
2232
2233 QDate QDateTime::date() const
2234 {
2235     return d->date;
2236 }
2237
2238 /*!
2239     Returns the time part of the datetime.
2240
2241     \sa setTime(), date(), timeSpec()
2242 */
2243
2244 QTime QDateTime::time() const
2245 {
2246     return d->time;
2247 }
2248
2249 /*!
2250     Returns the time specification of the datetime.
2251
2252     \sa setTimeSpec(), date(), time(), Qt::TimeSpec
2253 */
2254
2255 Qt::TimeSpec QDateTime::timeSpec() const
2256 {
2257     switch(d->spec)
2258     {
2259         case QDateTimePrivate::UTC:
2260             return Qt::UTC;
2261         case QDateTimePrivate::OffsetFromUTC:
2262             return Qt::OffsetFromUTC;
2263         default:
2264             return Qt::LocalTime;
2265     }
2266 }
2267
2268 /*!
2269     Sets the date part of this datetime to \a date.
2270     If no time is set, it is set to midnight.
2271
2272     \sa date(), setTime(), setTimeSpec()
2273 */
2274
2275 void QDateTime::setDate(const QDate &date)
2276 {
2277     detach();
2278     d->date = date;
2279     if (d->spec == QDateTimePrivate::LocalStandard
2280         || d->spec == QDateTimePrivate::LocalDST)
2281         d->spec = QDateTimePrivate::LocalUnknown;
2282     if (date.isValid() && !d->time.isValid())
2283         d->time = QTime(0, 0, 0);
2284 }
2285
2286 /*!
2287     Sets the time part of this datetime to \a time.
2288
2289     \sa time(), setDate(), setTimeSpec()
2290 */
2291
2292 void QDateTime::setTime(const QTime &time)
2293 {
2294     detach();
2295     if (d->spec == QDateTimePrivate::LocalStandard
2296         || d->spec == QDateTimePrivate::LocalDST)
2297         d->spec = QDateTimePrivate::LocalUnknown;
2298     d->time = time;
2299 }
2300
2301 /*!
2302     Sets the time specification used in this datetime to \a spec.
2303
2304     \sa timeSpec(), setDate(), setTime(), Qt::TimeSpec
2305 */
2306
2307 void QDateTime::setTimeSpec(Qt::TimeSpec spec)
2308 {
2309     detach();
2310
2311     switch(spec)
2312     {
2313         case Qt::UTC:
2314             d->spec = QDateTimePrivate::UTC;
2315             break;
2316         case Qt::OffsetFromUTC:
2317             d->spec = QDateTimePrivate::OffsetFromUTC;
2318             break;
2319         default:
2320             d->spec = QDateTimePrivate::LocalUnknown;
2321             break;
2322     }
2323 }
2324
2325 qint64 toMSecsSinceEpoch_helper(qint64 jd, int msecs)
2326 {
2327     qint64 days = jd - JULIAN_DAY_FOR_EPOCH;
2328     qint64 retval = (days * MSECS_PER_DAY) + msecs;
2329     return retval;
2330 }
2331
2332 /*!
2333     \since 4.7
2334
2335     Returns the datetime as the number of milliseconds that have passed
2336     since 1970-01-01T00:00:00.000, Coordinated Universal Time (Qt::UTC).
2337
2338     On systems that do not support time zones, this function will
2339     behave as if local time were Qt::UTC.
2340
2341     The behavior for this function is undefined if the datetime stored in
2342     this object is not valid. However, for all valid dates, this function
2343     returns a unique value.
2344
2345     \sa toTime_t(), setMSecsSinceEpoch()
2346 */
2347 qint64 QDateTime::toMSecsSinceEpoch() const
2348 {
2349     QDate utcDate;
2350     QTime utcTime;
2351     d->getUTC(utcDate, utcTime);
2352
2353     return toMSecsSinceEpoch_helper(utcDate.jd, utcTime.ds());
2354 }
2355
2356 /*!
2357     Returns the datetime as the number of seconds that have passed
2358     since 1970-01-01T00:00:00, Coordinated Universal Time (Qt::UTC).
2359
2360     On systems that do not support time zones, this function will
2361     behave as if local time were Qt::UTC.
2362
2363     \note This function returns a 32-bit unsigned integer, so it does not
2364     support dates before 1970, but it does support dates after
2365     2038-01-19T03:14:06, which may not be valid time_t values. Be careful
2366     when passing those time_t values to system functions, which could
2367     interpret them as negative dates.
2368
2369     If the date is outside the range 1970-01-01T00:00:00 to
2370     2106-02-07T06:28:14, this function returns -1 cast to an unsigned integer
2371     (i.e., 0xFFFFFFFF).
2372
2373     To get an extended range, use toMSecsSinceEpoch().
2374
2375     \sa toMSecsSinceEpoch(), setTime_t()
2376 */
2377
2378 uint QDateTime::toTime_t() const
2379 {
2380     qint64 retval = toMSecsSinceEpoch() / 1000;
2381     if (quint64(retval) >= Q_UINT64_C(0xFFFFFFFF))
2382         return uint(-1);
2383     return uint(retval);
2384 }
2385
2386 /*!
2387     \since 4.7
2388
2389     Sets the date and time given the number of milliseconds,\a msecs, that have
2390     passed since 1970-01-01T00:00:00.000, Coordinated Universal Time
2391     (Qt::UTC). On systems that do not support time zones this function
2392     will behave as if local time were Qt::UTC.
2393
2394     Note that there are possible values for \a msecs that lie outside the
2395     valid range of QDateTime, both negative and positive. The behavior of
2396     this function is undefined for those values.
2397
2398     \sa toMSecsSinceEpoch(), setTime_t()
2399 */
2400 void QDateTime::setMSecsSinceEpoch(qint64 msecs)
2401 {
2402     detach();
2403
2404     QDateTimePrivate::Spec oldSpec = d->spec;
2405
2406     int ddays = msecs / MSECS_PER_DAY;
2407     msecs %= MSECS_PER_DAY;
2408     if (msecs < 0) {
2409         // negative
2410         --ddays;
2411         msecs += MSECS_PER_DAY;
2412     }
2413
2414     d->date = QDate(1970, 1, 1).addDays(ddays);
2415     d->time = QTime().addMSecs(msecs);
2416     d->spec = QDateTimePrivate::UTC;
2417
2418     if (oldSpec != QDateTimePrivate::UTC)
2419         d->spec = d->getLocal(d->date, d->time);
2420 }
2421
2422 /*!
2423     \fn void QDateTime::setTime_t(uint seconds)
2424
2425     Sets the date and time given the number of \a seconds that have
2426     passed since 1970-01-01T00:00:00, Coordinated Universal Time
2427     (Qt::UTC). On systems that do not support time zones this function
2428     will behave as if local time were Qt::UTC.
2429
2430     \sa toTime_t()
2431 */
2432
2433 void QDateTime::setTime_t(uint secsSince1Jan1970UTC)
2434 {
2435     detach();
2436
2437     QDateTimePrivate::Spec oldSpec = d->spec;
2438
2439     d->date = QDate(1970, 1, 1).addDays(secsSince1Jan1970UTC / SECS_PER_DAY);
2440     d->time = QTime().addSecs(secsSince1Jan1970UTC % SECS_PER_DAY);
2441     d->spec = QDateTimePrivate::UTC;
2442
2443     if (oldSpec != QDateTimePrivate::UTC)
2444         d->spec = d->getLocal(d->date, d->time);
2445 }
2446
2447 #ifndef QT_NO_DATESTRING
2448 /*!
2449     \fn QString QDateTime::toString(Qt::DateFormat format) const
2450
2451     \overload
2452
2453     Returns the datetime as a string in the \a format given.
2454
2455     If the \a format is Qt::TextDate, the string is formatted in
2456     the default way. QDate::shortDayName(), QDate::shortMonthName(),
2457     and QTime::toString() are used to generate the string, so the
2458     day and month names will be localized names. An example of this
2459     formatting is "Wed May 20 03:40:13 1998".
2460
2461     If the \a format is Qt::ISODate, the string format corresponds
2462     to the ISO 8601 extended specification for representations of
2463     dates and times, taking the form YYYY-MM-DDTHH:MM:SS.
2464
2465     If the \a format is Qt::SystemLocaleShortDate or
2466     Qt::SystemLocaleLongDate, the string format depends on the locale
2467     settings of the system. Identical to calling
2468     QLocale::system().toString(datetime, QLocale::ShortFormat) or
2469     QLocale::system().toString(datetime, QLocale::LongFormat).
2470
2471     If the \a format is Qt::DefaultLocaleShortDate or
2472     Qt::DefaultLocaleLongDate, the string format depends on the
2473     default application locale. This is the locale set with
2474     QLocale::setDefault(), or the system locale if no default locale
2475     has been set. Identical to calling QLocale().toString(datetime,
2476     QLocale::ShortFormat) or QLocale().toString(datetime,
2477     QLocale::LongFormat).
2478
2479     If the datetime is invalid, an empty string will be returned.
2480
2481     \warning The Qt::ISODate format is only valid for years in the
2482     range 0 to 9999. This restriction may apply to locale-aware
2483     formats as well, depending on the locale settings.
2484
2485     \sa QDate::toString() QTime::toString() Qt::DateFormat
2486 */
2487
2488 QString QDateTime::toString(Qt::DateFormat f) const
2489 {
2490     QString buf;
2491     if (!isValid())
2492         return buf;
2493
2494     if (f == Qt::ISODate) {
2495         buf = d->date.toString(Qt::ISODate);
2496         if (buf.isEmpty())
2497             return QString();   // failed to convert
2498         buf += QLatin1Char('T');
2499         buf += d->time.toString(Qt::ISODate);
2500         switch (d->spec) {
2501         case QDateTimePrivate::UTC:
2502             buf += QLatin1Char('Z');
2503             break;
2504         case QDateTimePrivate::OffsetFromUTC: {
2505             int sign = d->utcOffset >= 0 ? 1: -1;
2506             buf += QString::fromLatin1("%1%2:%3").
2507                 arg(sign == 1 ? QLatin1Char('+') : QLatin1Char('-')).
2508                 arg(d->utcOffset * sign / SECS_PER_HOUR, 2, 10, QLatin1Char('0')).
2509                 arg((d->utcOffset / 60) % 60, 2, 10, QLatin1Char('0'));
2510             break;
2511         }
2512         default:
2513             break;
2514         }
2515     }
2516 #ifndef QT_NO_TEXTDATE
2517     else if (f == Qt::TextDate) {
2518 #ifndef Q_WS_WIN
2519         buf = d->date.shortDayName(d->date.dayOfWeek());
2520         buf += QLatin1Char(' ');
2521         buf += d->date.shortMonthName(d->date.month());
2522         buf += QLatin1Char(' ');
2523         buf += QString::number(d->date.day());
2524 #else
2525         wchar_t out[255];
2526         GetLocaleInfo(LOCALE_USER_DEFAULT, LOCALE_ILDATE, out, 255);
2527         QString winstr = QString::fromWCharArray(out);
2528         switch (winstr.toInt()) {
2529         case 1:
2530             buf = d->date.shortDayName(d->date.dayOfWeek());
2531             buf += QLatin1Char(' ');
2532             buf += QString::number(d->date.day());
2533             buf += QLatin1String(". ");
2534             buf += d->date.shortMonthName(d->date.month());
2535             break;
2536         default:
2537             buf = d->date.shortDayName(d->date.dayOfWeek());
2538             buf += QLatin1Char(' ');
2539             buf += d->date.shortMonthName(d->date.month());
2540             buf += QLatin1Char(' ');
2541             buf += QString::number(d->date.day());
2542         }
2543 #endif
2544         buf += QLatin1Char(' ');
2545         buf += d->time.toString();
2546         buf += QLatin1Char(' ');
2547         buf += QString::number(d->date.year());
2548     }
2549 #endif
2550     else {
2551         buf = d->date.toString(f);
2552         if (buf.isEmpty())
2553             return QString();   // failed to convert
2554         buf += QLatin1Char(' ');
2555         buf += d->time.toString(f);
2556     }
2557
2558     return buf;
2559 }
2560
2561 /*!
2562     Returns the datetime as a string. The \a format parameter
2563     determines the format of the result string.
2564
2565     These expressions may be used for the date:
2566
2567     \table
2568     \header \i Expression \i Output
2569     \row \i d \i the day as number without a leading zero (1 to 31)
2570     \row \i dd \i the day as number with a leading zero (01 to 31)
2571     \row \i ddd
2572             \i the abbreviated localized day name (e.g. 'Mon' to 'Sun').
2573             Uses QDate::shortDayName().
2574     \row \i dddd
2575             \i the long localized day name (e.g. 'Monday' to 'Qt::Sunday').
2576             Uses QDate::longDayName().
2577     \row \i M \i the month as number without a leading zero (1-12)
2578     \row \i MM \i the month as number with a leading zero (01-12)
2579     \row \i MMM
2580             \i the abbreviated localized month name (e.g. 'Jan' to 'Dec').
2581             Uses QDate::shortMonthName().
2582     \row \i MMMM
2583             \i the long localized month name (e.g. 'January' to 'December').
2584             Uses QDate::longMonthName().
2585     \row \i yy \i the year as two digit number (00-99)
2586     \row \i yyyy \i the year as four digit number
2587     \endtable
2588
2589     These expressions may be used for the time:
2590
2591     \table
2592     \header \i Expression \i Output
2593     \row \i h
2594          \i the hour without a leading zero (0 to 23 or 1 to 12 if AM/PM display)
2595     \row \i hh
2596          \i the hour with a leading zero (00 to 23 or 01 to 12 if AM/PM display)
2597     \row \i m \i the minute without a leading zero (0 to 59)
2598     \row \i mm \i the minute with a leading zero (00 to 59)
2599     \row \i s \i the second without a leading zero (0 to 59)
2600     \row \i ss \i the second with a leading zero (00 to 59)
2601     \row \i z \i the milliseconds without leading zeroes (0 to 999)
2602     \row \i zzz \i the milliseconds with leading zeroes (000 to 999)
2603     \row \i AP
2604             \i use AM/PM display. \e AP will be replaced by either "AM" or "PM".
2605     \row \i ap
2606             \i use am/pm display. \e ap will be replaced by either "am" or "pm".
2607     \endtable
2608
2609     All other input characters will be ignored. Any sequence of characters that
2610     are enclosed in singlequotes will be treated as text and not be used as an
2611     expression. Two consecutive singlequotes ("''") are replaced by a singlequote
2612     in the output.
2613
2614     Example format strings (assumed that the QDateTime is 21 May 2001
2615     14:13:09):
2616
2617     \table
2618     \header \i Format       \i Result
2619     \row \i dd.MM.yyyy      \i 21.05.2001
2620     \row \i ddd MMMM d yy   \i Tue May 21 01
2621     \row \i hh:mm:ss.zzz    \i 14:13:09.042
2622     \row \i h:m:s ap        \i 2:13:9 pm
2623     \endtable
2624
2625     If the datetime is invalid, an empty string will be returned.
2626
2627     \sa QDate::toString() QTime::toString()
2628 */
2629 QString QDateTime::toString(const QString& format) const
2630 {
2631     return fmtDateTime(format, &d->time, &d->date);
2632 }
2633 #endif //QT_NO_DATESTRING
2634
2635 /*!
2636     Returns a QDateTime object containing a datetime \a ndays days
2637     later than the datetime of this object (or earlier if \a ndays is
2638     negative).
2639
2640     \sa daysTo(), addMonths(), addYears(), addSecs()
2641 */
2642
2643 QDateTime QDateTime::addDays(int ndays) const
2644 {
2645     return QDateTime(d->date.addDays(ndays), d->time, timeSpec());
2646 }
2647
2648 /*!
2649     Returns a QDateTime object containing a datetime \a nmonths months
2650     later than the datetime of this object (or earlier if \a nmonths
2651     is negative).
2652
2653     \sa daysTo(), addDays(), addYears(), addSecs()
2654 */
2655
2656 QDateTime QDateTime::addMonths(int nmonths) const
2657 {
2658     return QDateTime(d->date.addMonths(nmonths), d->time, timeSpec());
2659 }
2660
2661 /*!
2662     Returns a QDateTime object containing a datetime \a nyears years
2663     later than the datetime of this object (or earlier if \a nyears is
2664     negative).
2665
2666     \sa daysTo(), addDays(), addMonths(), addSecs()
2667 */
2668
2669 QDateTime QDateTime::addYears(int nyears) const
2670 {
2671     return QDateTime(d->date.addYears(nyears), d->time, timeSpec());
2672 }
2673
2674 QDateTime QDateTimePrivate::addMSecs(const QDateTime &dt, qint64 msecs)
2675 {
2676     QDate utcDate;
2677     QTime utcTime;
2678     dt.d->getUTC(utcDate, utcTime);
2679
2680     addMSecs(utcDate, utcTime, msecs);
2681
2682     return QDateTime(utcDate, utcTime, Qt::UTC).toTimeSpec(dt.timeSpec());
2683 }
2684
2685 /*!
2686  Adds \a msecs to utcDate and \a utcTime as appropriate. It is assumed that
2687  utcDate and utcTime are adjusted to UTC.
2688
2689  \since 4.5
2690  \internal
2691  */
2692 void QDateTimePrivate::addMSecs(QDate &utcDate, QTime &utcTime, qint64 msecs)
2693 {
2694     uint dd = utcDate.jd;
2695     int tt = utcTime.ds();
2696     int sign = 1;
2697     if (msecs < 0) {
2698         msecs = -msecs;
2699         sign = -1;
2700     }
2701     if (msecs >= int(MSECS_PER_DAY)) {
2702         dd += sign * (msecs / MSECS_PER_DAY);
2703         msecs %= MSECS_PER_DAY;
2704     }
2705
2706     tt += sign * msecs;
2707     if (tt < 0) {
2708         tt = MSECS_PER_DAY - tt - 1;
2709         dd -= tt / MSECS_PER_DAY;
2710         tt = tt % MSECS_PER_DAY;
2711         tt = MSECS_PER_DAY - tt - 1;
2712     } else if (tt >= int(MSECS_PER_DAY)) {
2713         dd += tt / MSECS_PER_DAY;
2714         tt = tt % MSECS_PER_DAY;
2715     }
2716
2717     utcDate.jd = dd;
2718     utcTime.mds = tt;
2719 }
2720
2721 /*!
2722     Returns a QDateTime object containing a datetime \a s seconds
2723     later than the datetime of this object (or earlier if \a s is
2724     negative).
2725
2726     \sa addMSecs(), secsTo(), addDays(), addMonths(), addYears()
2727 */
2728
2729 QDateTime QDateTime::addSecs(int s) const
2730 {
2731     return d->addMSecs(*this, qint64(s) * 1000);
2732 }
2733
2734 /*!
2735     Returns a QDateTime object containing a datetime \a msecs miliseconds
2736     later than the datetime of this object (or earlier if \a msecs is
2737     negative).
2738
2739     \sa addSecs(), msecsTo(), addDays(), addMonths(), addYears()
2740 */
2741 QDateTime QDateTime::addMSecs(qint64 msecs) const
2742 {
2743     return d->addMSecs(*this, msecs);
2744 }
2745
2746 /*!
2747     Returns the number of days from this datetime to the \a other
2748     datetime. If the \a other datetime is earlier than this datetime,
2749     the value returned is negative.
2750
2751     \sa addDays(), secsTo(), msecsTo()
2752 */
2753
2754 int QDateTime::daysTo(const QDateTime &other) const
2755 {
2756     return d->date.daysTo(other.d->date);
2757 }
2758
2759 /*!
2760     Returns the number of seconds from this datetime to the \a other
2761     datetime. If the \a other datetime is earlier than this datetime,
2762     the value returned is negative.
2763
2764     Before performing the comparison, the two datetimes are converted
2765     to Qt::UTC to ensure that the result is correct if one of the two
2766     datetimes has daylight saving time (DST) and the other doesn't.
2767
2768     Example:
2769     \snippet doc/src/snippets/code/src_corelib_tools_qdatetime.cpp 11
2770
2771     \sa addSecs(), daysTo(), QTime::secsTo()
2772 */
2773
2774 int QDateTime::secsTo(const QDateTime &other) const
2775 {
2776     QDate date1, date2;
2777     QTime time1, time2;
2778
2779     d->getUTC(date1, time1);
2780     other.d->getUTC(date2, time2);
2781
2782     return (date1.daysTo(date2) * SECS_PER_DAY) + time1.secsTo(time2);
2783 }
2784
2785 /*!
2786     Returns the number of milliseconds from this datetime to the \a other
2787     datetime. If the \a other datetime is earlier than this datetime,
2788     the value returned is negative.
2789
2790     Before performing the comparison, the two datetimes are converted
2791     to Qt::UTC to ensure that the result is correct if one of the two
2792     datetimes has daylight saving time (DST) and the other doesn't.
2793
2794     \sa addMSecs(), daysTo(), QTime::msecsTo()
2795 */
2796
2797 qint64 QDateTime::msecsTo(const QDateTime &other) const
2798 {
2799     QDate selfDate;
2800     QDate otherDate;
2801     QTime selfTime;
2802     QTime otherTime;
2803
2804     d->getUTC(selfDate, selfTime);
2805     other.d->getUTC(otherDate, otherTime);
2806
2807     return (static_cast<qint64>(selfDate.daysTo(otherDate)) * static_cast<qint64>(MSECS_PER_DAY))
2808            + static_cast<qint64>(selfTime.msecsTo(otherTime));
2809 }
2810
2811
2812 /*!
2813     \fn QDateTime QDateTime::toTimeSpec(Qt::TimeSpec specification) const
2814
2815     Returns a copy of this datetime configured to use the given time
2816     \a specification.
2817
2818     \sa timeSpec(), toUTC(), toLocalTime()
2819 */
2820
2821 QDateTime QDateTime::toTimeSpec(Qt::TimeSpec spec) const
2822 {
2823     if ((d->spec == QDateTimePrivate::UTC) == (spec == Qt::UTC))
2824         return *this;
2825
2826     QDateTime ret;
2827     if (spec == Qt::UTC) {
2828         d->getUTC(ret.d->date, ret.d->time);
2829         ret.d->spec = QDateTimePrivate::UTC;
2830     } else {
2831         ret.d->spec = d->getLocal(ret.d->date, ret.d->time);
2832     }
2833     return ret;
2834 }
2835
2836 /*!
2837     Returns true if this datetime is equal to the \a other datetime;
2838     otherwise returns false.
2839
2840     \sa operator!=()
2841 */
2842
2843 bool QDateTime::operator==(const QDateTime &other) const
2844 {
2845     if (d->spec == other.d->spec && d->utcOffset == other.d->utcOffset)
2846         return d->time == other.d->time && d->date == other.d->date;
2847     else {
2848         QDate date1, date2;
2849         QTime time1, time2;
2850
2851         d->getUTC(date1, time1);
2852         other.d->getUTC(date2, time2);
2853         return time1 == time2 && date1 == date2;
2854     }
2855 }
2856
2857 /*!
2858     \fn bool QDateTime::operator!=(const QDateTime &other) const
2859
2860     Returns true if this datetime is different from the \a other
2861     datetime; otherwise returns false.
2862
2863     Two datetimes are different if either the date, the time, or the
2864     time zone components are different.
2865
2866     \sa operator==()
2867 */
2868
2869 /*!
2870     Returns true if this datetime is earlier than the \a other
2871     datetime; otherwise returns false.
2872 */
2873
2874 bool QDateTime::operator<(const QDateTime &other) const
2875 {
2876     if (d->spec == other.d->spec && d->spec != QDateTimePrivate::OffsetFromUTC) {
2877         if (d->date != other.d->date)
2878             return d->date < other.d->date;
2879         return d->time < other.d->time;
2880     } else {
2881         QDate date1, date2;
2882         QTime time1, time2;
2883         d->getUTC(date1, time1);
2884         other.d->getUTC(date2, time2);
2885         if (date1 != date2)
2886             return date1 < date2;
2887         return time1 < time2;
2888     }
2889 }
2890
2891 /*!
2892     \fn bool QDateTime::operator<=(const QDateTime &other) const
2893
2894     Returns true if this datetime is earlier than or equal to the
2895     \a other datetime; otherwise returns false.
2896 */
2897
2898 /*!
2899     \fn bool QDateTime::operator>(const QDateTime &other) const
2900
2901     Returns true if this datetime is later than the \a other datetime;
2902     otherwise returns false.
2903 */
2904
2905 /*!
2906     \fn bool QDateTime::operator>=(const QDateTime &other) const
2907
2908     Returns true if this datetime is later than or equal to the
2909     \a other datetime; otherwise returns false.
2910 */
2911
2912 /*!
2913     \fn QDateTime QDateTime::currentDateTime()
2914     Returns the current datetime, as reported by the system clock, in
2915     the local time zone.
2916
2917     \sa currentDateTimeUtc(), QDate::currentDate(), QTime::currentTime(), toTimeSpec()
2918 */
2919
2920 /*!
2921     \fn QDateTime QDateTime::currentDateTimeUtc()
2922     \since 4.7
2923     Returns the current datetime, as reported by the system clock, in
2924     UTC.
2925
2926     \sa currentDateTime(), QDate::currentDate(), QTime::currentTime(), toTimeSpec()
2927 */
2928
2929 /*!
2930     \fn qint64 QDateTime::currentMSecsSinceEpoch()
2931     \since 4.7
2932
2933     Returns the number of milliseconds since 1970-01-01T00:00:00 Universal
2934     Coordinated Time. This number is like the POSIX time_t variable, but
2935     expressed in milliseconds instead.
2936
2937     \sa currentDateTime(), currentDateTimeUtc(), toTime_t(), toTimeSpec()
2938 */
2939
2940 static inline uint msecsFromDecomposed(int hour, int minute, int sec, int msec = 0)
2941 {
2942     return MSECS_PER_HOUR * hour + MSECS_PER_MIN * minute + 1000 * sec + msec;
2943 }
2944
2945 #if defined(Q_OS_WIN)
2946 QDate QDate::currentDate()
2947 {
2948     QDate d;
2949     SYSTEMTIME st;
2950     memset(&st, 0, sizeof(SYSTEMTIME));
2951     GetLocalTime(&st);
2952     d.jd = julianDayFromDate(st.wYear, st.wMonth, st.wDay);
2953     return d;
2954 }
2955
2956 QTime QTime::currentTime()
2957 {
2958     QTime ct;
2959     SYSTEMTIME st;
2960     memset(&st, 0, sizeof(SYSTEMTIME));
2961     GetLocalTime(&st);
2962     ct.mds = msecsFromDecomposed(st.wHour, st.wMinute, st.wSecond, st.wMilliseconds);
2963 #if defined(Q_OS_WINCE)
2964     ct.startTick = GetTickCount() % MSECS_PER_DAY;
2965 #endif
2966     return ct;
2967 }
2968
2969 QDateTime QDateTime::currentDateTime()
2970 {
2971     QDate d;
2972     QTime t;
2973     SYSTEMTIME st;
2974     memset(&st, 0, sizeof(SYSTEMTIME));
2975     GetLocalTime(&st);
2976     d.jd = julianDayFromDate(st.wYear, st.wMonth, st.wDay);
2977     t.mds = msecsFromDecomposed(st.wHour, st.wMinute, st.wSecond, st.wMilliseconds);
2978     return QDateTime(d, t);
2979 }
2980
2981 QDateTime QDateTime::currentDateTimeUtc()
2982 {
2983     QDate d;
2984     QTime t;
2985     SYSTEMTIME st;
2986     memset(&st, 0, sizeof(SYSTEMTIME));
2987     GetSystemTime(&st);
2988     d.jd = julianDayFromDate(st.wYear, st.wMonth, st.wDay);
2989     t.mds = msecsFromDecomposed(st.wHour, st.wMinute, st.wSecond, st.wMilliseconds);
2990     return QDateTime(d, t, Qt::UTC);
2991 }
2992
2993 qint64 QDateTime::currentMSecsSinceEpoch()
2994 {
2995     QDate d;
2996     QTime t;
2997     SYSTEMTIME st;
2998     memset(&st, 0, sizeof(SYSTEMTIME));
2999     GetSystemTime(&st);
3000
3001     return msecsFromDecomposed(st.wHour, st.wMinute, st.wSecond, st.wMilliseconds) +
3002             qint64(julianDayFromGregorianDate(st.wYear, st.wMonth, st.wDay)
3003                    - julianDayFromGregorianDate(1970, 1, 1)) * Q_INT64_C(86400000);
3004 }
3005
3006 #elif defined(Q_OS_SYMBIAN)
3007 QDate QDate::currentDate()
3008 {
3009     QDate d;
3010     TTime localTime;
3011     localTime.HomeTime();
3012     TDateTime localDateTime = localTime.DateTime();
3013     // months and days are zero indexed
3014     d.jd = julianDayFromDate(localDateTime.Year(), localDateTime.Month() + 1, localDateTime.Day() + 1 );
3015     return d;
3016 }
3017
3018 QTime QTime::currentTime()
3019 {
3020     QTime ct;
3021     TTime localTime;
3022     localTime.HomeTime();
3023     TDateTime localDateTime = localTime.DateTime();
3024     ct.mds = msecsFromDecomposed(localDateTime.Hour(), localDateTime.Minute(),
3025                                  localDateTime.Second(), localDateTime.MicroSecond() / 1000);
3026     return ct;
3027 }
3028
3029 QDateTime QDateTime::currentDateTime()
3030 {
3031     QDate d;
3032     QTime ct;
3033     TTime localTime;
3034     localTime.HomeTime();
3035     TDateTime localDateTime = localTime.DateTime();
3036     // months and days are zero indexed
3037     d.jd = julianDayFromDate(localDateTime.Year(), localDateTime.Month() + 1, localDateTime.Day() + 1);
3038     ct.mds = msecsFromDecomposed(localDateTime.Hour(), localDateTime.Minute(),
3039                                  localDateTime.Second(), localDateTime.MicroSecond() / 1000);
3040     return QDateTime(d, ct);
3041 }
3042
3043 QDateTime QDateTime::currentDateTimeUtc()
3044 {
3045     QDate d;
3046     QTime ct;
3047     TTime gmTime;
3048     gmTime.UniversalTime();
3049     TDateTime gmtDateTime = gmTime.DateTime();
3050     // months and days are zero indexed
3051     d.jd = julianDayFromDate(gmtDateTime.Year(), gmtDateTime.Month() + 1, gmtDateTime.Day() + 1);
3052     ct.mds = msecsFromDecomposed(gmtDateTime.Hour(), gmtDateTime.Minute(),
3053                                  gmtDateTime.Second(), gmtDateTime.MicroSecond() / 1000);
3054     return QDateTime(d, ct, Qt::UTC);
3055 }
3056
3057 qint64 QDateTime::currentMSecsSinceEpoch()
3058 {
3059     QDate d;
3060     QTime ct;
3061     TTime gmTime;
3062     gmTime.UniversalTime();
3063     TDateTime gmtDateTime = gmTime.DateTime();
3064
3065     // according to the documentation, the value is:
3066     // "a date and time as a number of microseconds since midnight, January 1st, 0 AD nominal Gregorian"
3067     qint64 value = gmTime.Int64();
3068
3069     // whereas 1970-01-01T00:00:00 is (in the same representation):
3070     //   ((1970 * 365) + (1970 / 4) - (1970 / 100) + (1970 / 400) - 13) * 86400 * 1000000
3071     static const qint64 unixEpoch = Q_INT64_C(0xdcddb30f2f8000);
3072
3073     return (value - unixEpoch) / 1000;
3074 }
3075
3076 #elif defined(Q_OS_UNIX)
3077 QDate QDate::currentDate()
3078 {
3079     QDate d;
3080     // posix compliant system
3081     time_t ltime;
3082     time(&ltime);
3083     struct tm *t = 0;
3084
3085 #if !defined(QT_NO_THREAD) && defined(_POSIX_THREAD_SAFE_FUNCTIONS)
3086     // use the reentrant version of localtime() where available
3087     tzset();
3088     struct tm res;
3089     t = localtime_r(&ltime, &res);
3090 #else
3091     t = localtime(&ltime);
3092 #endif // !QT_NO_THREAD && _POSIX_THREAD_SAFE_FUNCTIONS
3093
3094     d.jd = julianDayFromDate(t->tm_year + 1900, t->tm_mon + 1, t->tm_mday);
3095     return d;
3096 }
3097
3098 QTime QTime::currentTime()
3099 {
3100     QTime ct;
3101     // posix compliant system
3102     struct timeval tv;
3103     gettimeofday(&tv, 0);
3104     time_t ltime = tv.tv_sec;
3105     struct tm *t = 0;
3106
3107 #if !defined(QT_NO_THREAD) && defined(_POSIX_THREAD_SAFE_FUNCTIONS)
3108     // use the reentrant version of localtime() where available
3109     tzset();
3110     struct tm res;
3111     t = localtime_r(&ltime, &res);
3112 #else
3113     t = localtime(&ltime);
3114 #endif
3115     Q_CHECK_PTR(t);
3116
3117     ct.mds = msecsFromDecomposed(t->tm_hour, t->tm_min, t->tm_sec, tv.tv_usec / 1000);
3118     return ct;
3119 }
3120
3121 QDateTime QDateTime::currentDateTime()
3122 {
3123     // posix compliant system
3124     // we have milliseconds
3125     struct timeval tv;
3126     gettimeofday(&tv, 0);
3127     time_t ltime = tv.tv_sec;
3128     struct tm *t = 0;
3129
3130 #if !defined(QT_NO_THREAD) && defined(_POSIX_THREAD_SAFE_FUNCTIONS)
3131     // use the reentrant version of localtime() where available
3132     tzset();
3133     struct tm res;
3134     t = localtime_r(&ltime, &res);
3135 #else
3136     t = localtime(&ltime);
3137 #endif
3138
3139     QDateTime dt;
3140     dt.d->time.mds = msecsFromDecomposed(t->tm_hour, t->tm_min, t->tm_sec, tv.tv_usec / 1000);
3141
3142     dt.d->date.jd = julianDayFromDate(t->tm_year + 1900, t->tm_mon + 1, t->tm_mday);
3143     dt.d->spec = t->tm_isdst > 0  ? QDateTimePrivate::LocalDST :
3144                  t->tm_isdst == 0 ? QDateTimePrivate::LocalStandard :
3145                  QDateTimePrivate::LocalUnknown;
3146     return dt;
3147 }
3148
3149 QDateTime QDateTime::currentDateTimeUtc()
3150 {
3151     // posix compliant system
3152     // we have milliseconds
3153     struct timeval tv;
3154     gettimeofday(&tv, 0);
3155     time_t ltime = tv.tv_sec;
3156     struct tm *t = 0;
3157
3158 #if !defined(QT_NO_THREAD) && defined(_POSIX_THREAD_SAFE_FUNCTIONS)
3159     // use the reentrant version of localtime() where available
3160     struct tm res;
3161     t = gmtime_r(&ltime, &res);
3162 #else
3163     t = gmtime(&ltime);
3164 #endif
3165
3166     QDateTime dt;
3167     dt.d->time.mds = msecsFromDecomposed(t->tm_hour, t->tm_min, t->tm_sec, tv.tv_usec / 1000);
3168
3169     dt.d->date.jd = julianDayFromDate(t->tm_year + 1900, t->tm_mon + 1, t->tm_mday);
3170     dt.d->spec = QDateTimePrivate::UTC;
3171     return dt;
3172 }
3173
3174 qint64 QDateTime::currentMSecsSinceEpoch()
3175 {
3176     // posix compliant system
3177     // we have milliseconds
3178     struct timeval tv;
3179     gettimeofday(&tv, 0);
3180     return qint64(tv.tv_sec) * Q_INT64_C(1000) + tv.tv_usec / 1000;
3181 }
3182
3183 #else
3184 #error "What system is this?"
3185 #endif
3186
3187 /*!
3188   \since 4.2
3189
3190   Returns a datetime whose date and time are the number of \a seconds
3191   that have passed since 1970-01-01T00:00:00, Coordinated Universal
3192   Time (Qt::UTC). On systems that do not support time zones, the time
3193   will be set as if local time were Qt::UTC.
3194
3195   \sa toTime_t(), setTime_t()
3196 */
3197 QDateTime QDateTime::fromTime_t(uint seconds)
3198 {
3199     QDateTime d;
3200     d.setTime_t(seconds);
3201     return d;
3202 }
3203
3204 /*!
3205   \since 4.7
3206
3207   Returns a datetime whose date and time are the number of milliseconds, \a msecs,
3208   that have passed since 1970-01-01T00:00:00.000, Coordinated Universal
3209   Time (Qt::UTC). On systems that do not support time zones, the time
3210   will be set as if local time were Qt::UTC.
3211
3212   Note that there are possible values for \a msecs that lie outside the valid
3213   range of QDateTime, both negative and positive. The behavior of this
3214   function is undefined for those values.
3215
3216   \sa toTime_t(), setTime_t()
3217 */
3218 QDateTime QDateTime::fromMSecsSinceEpoch(qint64 msecs)
3219 {
3220     QDateTime d;
3221     d.setMSecsSinceEpoch(msecs);
3222     return d;
3223 }
3224
3225 /*!
3226  \since 4.4
3227  \internal
3228
3229  Sets the offset from UTC to \a seconds, and also sets timeSpec() to
3230  Qt::OffsetFromUTC.
3231
3232  The maximum and minimum offset is 14 positive or negative hours.  If
3233  \a seconds is larger or smaller than that, the result is undefined.
3234
3235  0 as offset is identical to UTC. Therefore, if \a seconds is 0, the
3236  timeSpec() will be set to Qt::UTC. Hence the UTC offset always
3237  relates to UTC, and can never relate to local time.
3238
3239  \sa isValid(), utcOffset()
3240  */
3241 void QDateTime::setUtcOffset(int seconds)
3242 {
3243     detach();
3244
3245     /* The motivation to also setting d->spec is to ensure that the QDateTime
3246      * instance stay in well-defined states all the time, instead of that
3247      * we instruct the user to ensure it. */
3248     if(seconds == 0)
3249         d->spec = QDateTimePrivate::UTC;
3250     else
3251         d->spec = QDateTimePrivate::OffsetFromUTC;
3252
3253     /* Even if seconds is 0 we assign it to utcOffset. */
3254     d->utcOffset = seconds;
3255 }
3256
3257 /*!
3258  \since 4.4
3259  \internal
3260
3261  Returns the UTC offset in seconds. If the timeSpec() isn't
3262  Qt::OffsetFromUTC, 0 is returned. However, since 0 is a valid UTC
3263  offset the return value of this function cannot be used to determine
3264  whether a utcOffset() is used or is valid, timeSpec() must be
3265  checked.
3266
3267  Likewise, if this QDateTime() is invalid or if timeSpec() isn't
3268  Qt::OffsetFromUTC, 0 is returned.
3269
3270  The UTC offset only applies if the timeSpec() is Qt::OffsetFromUTC.
3271
3272  \sa isValid(), setUtcOffset()
3273  */
3274 int QDateTime::utcOffset() const
3275 {
3276     if(isValid() && d->spec == QDateTimePrivate::OffsetFromUTC)
3277         return d->utcOffset;
3278     else
3279         return 0;
3280 }
3281
3282 #ifndef QT_NO_DATESTRING
3283
3284 static int fromShortMonthName(const QString &monthName)
3285 {
3286     // Assume that English monthnames are the default
3287     for (int i = 0; i < 12; ++i) {
3288         if (monthName == QLatin1String(qt_shortMonthNames[i]))
3289             return i + 1;
3290     }
3291     // If English names can't be found, search the localized ones
3292     for (int i = 1; i <= 12; ++i) {
3293         if (monthName == QDate::shortMonthName(i))
3294             return i;
3295     }
3296     return -1;
3297 }
3298
3299 /*!
3300     \fn QDateTime QDateTime::fromString(const QString &string, Qt::DateFormat format)
3301
3302     Returns the QDateTime represented by the \a string, using the
3303     \a format given, or an invalid datetime if this is not possible.
3304
3305     Note for Qt::TextDate: It is recommended that you use the
3306     English short month names (e.g. "Jan"). Although localized month
3307     names can also be used, they depend on the user's locale settings.
3308 */
3309 QDateTime QDateTime::fromString(const QString& s, Qt::DateFormat f)
3310 {
3311     if (s.isEmpty()) {
3312         return QDateTime();
3313     }
3314
3315     switch (f) {
3316     case Qt::ISODate: {
3317         QString tmp = s;
3318         Qt::TimeSpec ts = Qt::LocalTime;
3319         const QDate date = QDate::fromString(tmp.left(10), Qt::ISODate);
3320         if (tmp.size() == 10)
3321             return QDateTime(date);
3322
3323         tmp = tmp.mid(11);
3324
3325         // Recognize UTC specifications
3326         if (tmp.endsWith(QLatin1Char('Z'))) {
3327             ts = Qt::UTC;
3328             tmp.chop(1);
3329         }
3330
3331         // Recognize timezone specifications
3332         QRegExp rx(QLatin1String("[+-]"));
3333         if (tmp.contains(rx)) {
3334             int idx = tmp.indexOf(rx);
3335             QString tmp2 = tmp.mid(idx);
3336             tmp = tmp.left(idx);
3337             bool ok = true;
3338             int ntzhour = 1;
3339             int ntzminute = 3;
3340             if ( tmp2.indexOf(QLatin1Char(':')) == 3 )
3341                ntzminute = 4;
3342             const int tzhour(tmp2.mid(ntzhour, 2).toInt(&ok));
3343             const int tzminute(tmp2.mid(ntzminute, 2).toInt(&ok));
3344             QTime tzt(tzhour, tzminute);
3345             int utcOffset = (tzt.hour() * 60 + tzt.minute()) * 60;
3346             if ( utcOffset != 0 ) {
3347                 ts = Qt::OffsetFromUTC;
3348                 QDateTime dt(date, QTime::fromString(tmp, Qt::ISODate), ts);
3349                 dt.setUtcOffset( utcOffset * (tmp2.startsWith(QLatin1Char('-')) ? -1 : 1) );
3350                 return dt;
3351             }
3352         }
3353         return QDateTime(date, QTime::fromString(tmp, Qt::ISODate), ts);
3354     }
3355     case Qt::SystemLocaleDate:
3356     case Qt::SystemLocaleShortDate:
3357     case Qt::SystemLocaleLongDate:
3358         return fromString(s, QLocale::system().dateTimeFormat(f == Qt::SystemLocaleLongDate ? QLocale::LongFormat
3359                                                                                             : QLocale::ShortFormat));
3360     case Qt::LocaleDate:
3361     case Qt::DefaultLocaleShortDate:
3362     case Qt::DefaultLocaleLongDate:
3363         return fromString(s, QLocale().dateTimeFormat(f == Qt::DefaultLocaleLongDate ? QLocale::LongFormat
3364                                                                                      : QLocale::ShortFormat));
3365 #if !defined(QT_NO_TEXTDATE)
3366     case Qt::TextDate: {
3367         QStringList parts = s.split(QLatin1Char(' '), QString::SkipEmptyParts);
3368
3369         if ((parts.count() < 5) || (parts.count() > 6)) {
3370             return QDateTime();
3371         }
3372
3373         // Accept "Sun Dec 1 13:02:00 1974" and "Sun 1. Dec 13:02:00 1974"
3374         int month = -1, day = -1;
3375         bool ok;
3376
3377         month = fromShortMonthName(parts.at(1));
3378         if (month != -1) {
3379             day = parts.at(2).toInt(&ok);
3380             if (!ok)
3381                 day = -1;
3382         }
3383
3384         if (month == -1 || day == -1) {
3385             // first variant failed, lets try the other
3386             month = fromShortMonthName(parts.at(2));
3387             if (month != -1) {
3388                 QString dayStr = parts.at(1);
3389                 if (dayStr.endsWith(QLatin1Char('.'))) {
3390                     dayStr.chop(1);
3391                     day = dayStr.toInt(&ok);
3392                     if (!ok)
3393                         day = -1;
3394                 } else {
3395                     day = -1;
3396                 }
3397             }
3398         }
3399
3400         if (month == -1 || day == -1) {
3401             // both variants failed, give up
3402             return QDateTime();
3403         }
3404
3405         int year;
3406         QStringList timeParts = parts.at(3).split(QLatin1Char(':'));
3407         if ((timeParts.count() == 3) || (timeParts.count() == 2)) {
3408             year = parts.at(4).toInt(&ok);
3409             if (!ok)
3410                 return QDateTime();
3411         } else {
3412             timeParts = parts.at(4).split(QLatin1Char(':'));
3413             if ((timeParts.count() != 3) && (timeParts.count() != 2))
3414                 return QDateTime();
3415             year = parts.at(3).toInt(&ok);
3416             if (!ok)
3417                 return QDateTime();
3418         }
3419
3420         int hour = timeParts.at(0).toInt(&ok);
3421         if (!ok) {
3422             return QDateTime();
3423         }
3424
3425         int minute = timeParts.at(1).toInt(&ok);
3426         if (!ok) {
3427             return QDateTime();
3428         }
3429
3430         int second = (timeParts.count() > 2) ? timeParts.at(2).toInt(&ok) : 0;
3431         if (!ok) {
3432             return QDateTime();
3433         }
3434
3435         QDate date(year, month, day);
3436         QTime time(hour, minute, second);
3437
3438         if (parts.count() == 5)
3439             return QDateTime(date, time, Qt::LocalTime);
3440
3441         QString tz = parts.at(5);
3442         if (!tz.startsWith(QLatin1String("GMT"), Qt::CaseInsensitive))
3443             return QDateTime();
3444         QDateTime dt(date, time, Qt::UTC);
3445         if (tz.length() > 3) {
3446             int tzoffset = 0;
3447             QChar sign = tz.at(3);
3448             if ((sign != QLatin1Char('+'))
3449                 && (sign != QLatin1Char('-'))) {
3450                 return QDateTime();
3451             }
3452             int tzhour = tz.mid(4, 2).toInt(&ok);
3453             if (!ok)
3454                 return QDateTime();
3455             int tzminute = tz.mid(6).toInt(&ok);
3456             if (!ok)
3457                 return QDateTime();
3458             tzoffset = (tzhour*60 + tzminute) * 60;
3459             if (sign == QLatin1Char('-'))
3460                 tzoffset = -tzoffset;
3461             dt.setUtcOffset(tzoffset);
3462         }
3463         return dt.toLocalTime();
3464     }
3465 #endif //QT_NO_TEXTDATE
3466     }
3467
3468     return QDateTime();
3469 }
3470
3471 /*!
3472     \fn QDateTime::fromString(const QString &string, const QString &format)
3473
3474     Returns the QDateTime represented by the \a string, using the \a
3475     format given, or an invalid datetime if the string cannot be parsed.
3476
3477     These expressions may be used for the date part of the format string:
3478
3479     \table
3480     \header \i Expression \i Output
3481     \row \i d \i the day as number without a leading zero (1 to 31)
3482     \row \i dd \i the day as number with a leading zero (01 to 31)
3483     \row \i ddd
3484             \i the abbreviated localized day name (e.g. 'Mon' to 'Sun').
3485             Uses QDate::shortDayName().
3486     \row \i dddd
3487             \i the long localized day name (e.g. 'Monday' to 'Sunday').
3488             Uses QDate::longDayName().
3489     \row \i M \i the month as number without a leading zero (1-12)
3490     \row \i MM \i the month as number with a leading zero (01-12)
3491     \row \i MMM
3492             \i the abbreviated localized month name (e.g. 'Jan' to 'Dec').
3493             Uses QDate::shortMonthName().
3494     \row \i MMMM
3495             \i the long localized month name (e.g. 'January' to 'December').
3496             Uses QDate::longMonthName().
3497     \row \i yy \i the year as two digit number (00-99)
3498     \row \i yyyy \i the year as four digit number
3499     \endtable
3500
3501     \note Unlike the other version of this function, day and month names must
3502     be given in the user's local language. It is only possible to use the English
3503     names if the user's language is English.
3504
3505     These expressions may be used for the time part of the format string:
3506
3507     \table
3508     \header \i Expression \i Output
3509     \row \i h
3510             \i the hour without a leading zero (0 to 23 or 1 to 12 if AM/PM display)
3511     \row \i hh
3512             \i the hour with a leading zero (00 to 23 or 01 to 12 if AM/PM display)
3513     \row \i H
3514             \i the hour without a leading zero (0 to 23, even with AM/PM display)
3515     \row \i HH
3516             \i the hour with a leading zero (00 to 23, even with AM/PM display)
3517     \row \i m \i the minute without a leading zero (0 to 59)
3518     \row \i mm \i the minute with a leading zero (00 to 59)
3519     \row \i s \i the second without a leading zero (0 to 59)
3520     \row \i ss \i the second with a leading zero (00 to 59)
3521     \row \i z \i the milliseconds without leading zeroes (0 to 999)
3522     \row \i zzz \i the milliseconds with leading zeroes (000 to 999)
3523     \row \i AP or A
3524          \i interpret as an AM/PM time. \e AP must be either "AM" or "PM".
3525     \row \i ap or a
3526          \i Interpret as an AM/PM time. \e ap must be either "am" or "pm".
3527     \endtable
3528
3529     All other input characters will be treated as text. Any sequence
3530     of characters that are enclosed in singlequotes will also be
3531     treated as text and not be used as an expression.
3532
3533     \snippet doc/src/snippets/code/src_corelib_tools_qdatetime.cpp 12
3534
3535     If the format is not satisfied an invalid QDateTime is returned.
3536     The expressions that don't have leading zeroes (d, M, h, m, s, z) will be
3537     greedy. This means that they will use two digits even if this will
3538     put them outside the range and/or leave too few digits for other
3539     sections.
3540
3541     \snippet doc/src/snippets/code/src_corelib_tools_qdatetime.cpp 13
3542
3543     This could have meant 1 January 00:30.00 but the M will grab
3544     two digits.
3545
3546     For any field that is not represented in the format the following
3547     defaults are used:
3548
3549     \table
3550     \header \i Field  \i Default value
3551     \row    \i Year   \i 1900
3552     \row    \i Month  \i 1 (January)
3553     \row    \i Day    \i 1
3554     \row    \i Hour   \i 0
3555     \row    \i Minute \i 0
3556     \row    \i Second \i 0
3557     \endtable
3558
3559     For example:
3560
3561     \snippet doc/src/snippets/code/src_corelib_tools_qdatetime.cpp 14
3562
3563     \sa QDate::fromString() QTime::fromString() QDate::toString()
3564     QDateTime::toString() QTime::toString()
3565 */
3566
3567 QDateTime QDateTime::fromString(const QString &string, const QString &format)
3568 {
3569 #ifndef QT_BOOTSTRAPPED
3570     QTime time;
3571     QDate date;
3572
3573     QDateTimeParser dt(QVariant::DateTime, QDateTimeParser::FromString);
3574     if (dt.parseFormat(format) && dt.fromString(string, &date, &time))
3575         return QDateTime(date, time);
3576 #else
3577     Q_UNUSED(string);
3578     Q_UNUSED(format);
3579 #endif
3580     return QDateTime(QDate(), QTime(-1, -1, -1));
3581 }
3582
3583 #endif // QT_NO_DATESTRING
3584 /*!
3585     \fn QDateTime QDateTime::toLocalTime() const
3586
3587     Returns a datetime containing the date and time information in
3588     this datetime, but specified using the Qt::LocalTime definition.
3589
3590     \sa toTimeSpec()
3591 */
3592
3593 /*!
3594     \fn QDateTime QDateTime::toUTC() const
3595
3596     Returns a datetime containing the date and time information in
3597     this datetime, but specified using the Qt::UTC definition.
3598
3599     \sa toTimeSpec()
3600 */
3601
3602 /*! \internal
3603  */
3604 void QDateTime::detach()
3605 {
3606     d.detach();
3607 }
3608
3609 /*****************************************************************************
3610   Date/time stream functions
3611  *****************************************************************************/
3612
3613 #ifndef QT_NO_DATASTREAM
3614 /*!
3615     \relates QDate
3616
3617     Writes the \a date to stream \a out.
3618
3619     \sa {Serializing Qt Data Types}
3620 */
3621
3622 QDataStream &operator<<(QDataStream &out, const QDate &date)
3623 {
3624     return out << (quint32)(date.jd);
3625 }
3626
3627 /*!
3628     \relates QDate
3629
3630     Reads a date from stream \a in into the \a date.
3631
3632     \sa {Serializing Qt Data Types}
3633 */
3634
3635 QDataStream &operator>>(QDataStream &in, QDate &date)
3636 {
3637     quint32 jd;
3638     in >> jd;
3639     date.jd = jd;
3640     return in;
3641 }
3642
3643 /*!
3644     \relates QTime
3645
3646     Writes \a time to stream \a out.
3647
3648     \sa {Serializing Qt Data Types}
3649 */
3650
3651 QDataStream &operator<<(QDataStream &out, const QTime &time)
3652 {
3653     return out << quint32(time.mds);
3654 }
3655
3656 /*!
3657     \relates QTime
3658
3659     Reads a time from stream \a in into the given \a time.
3660
3661     \sa {Serializing Qt Data Types}
3662 */
3663
3664 QDataStream &operator>>(QDataStream &in, QTime &time)
3665 {
3666     quint32 ds;
3667     in >> ds;
3668     time.mds = int(ds);
3669     return in;
3670 }
3671
3672 /*!
3673     \relates QDateTime
3674