1/*
2 Copyright 2010 John Layt <john@layt.net>
3
4 This library is free software; you can redistribute it and/or
5 modify it under the terms of the GNU Library General Public
6 License as published by the Free Software Foundation; either
7 version 2 of the License, or (at your option) any later version.
8
9 This library is distributed in the hope that it will be useful,
10 but WITHOUT ANY WARRANTY; without even the implied warranty of
11 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 Library General Public License for more details.
13
14 You should have received a copy of the GNU Library General Public License
15 along with this library; see the file COPYING.LIB. If not, write to
16 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
17 Boston, MA 02110-1301, USA.
18*/
19
20#ifndef KLOCALIZEDDATE_H
21#define KLOCALIZEDDATE_H
22
23#include <QtCore/QString>
24#include <QtCore/QDate>
25
26#include <kdecore_export.h>
27#include "kcalendarsystem.h"
28#include "klocale.h"
29
30class KLocalizedDatePrivate;
31/**
32 * @short A class representing a date localized using the local calendar system, language and formats
33 *
34 * Topics:
35 * - @ref intro
36 * - @ref calsys
37 * - @ref custom
38 * - @ref formatting
39 * - @ref maths
40 *
41 * @section intro Introduction
42 *
43 * This class provides a simple and convenient way to localize dates
44 *
45 * @section calsys Calendar System
46 *
47 * KDE supports the use of different calendar systems.
48 *
49 * @section custom Default and Custom Locale and Calendar System
50 *
51 * In most cases you will want to use the default Global Locale and Calendar
52 * System, in which case you need only create a default KLocalizedDate. If
53 * however you specifically need a different Calendar System or Locale settings
54 * then you need to take some extra steps.
55 *
56 * The simplest method is just changing the Calendar System while keeping the
57 * current Locale settings. This is easily done using setCalendarSystem()
58 * which will copy the current Locale being used and apply this to the new
59 * Calendar System. Note this means any changes to the old locale settings,
60 * either the Global Locale or a custom Locale (see below) will not apply
61 * to that date instance.
62 *
63 * You may however wish to use a custom Locale with the Calendar System.
64 * For example, if you want your app to normally show dates using the Global
65 * Locale and Calendar System, but wish to show an info box with the Islamic
66 * date in Arabic language and format, then you need a custom Locale to do
67 * this.
68 *
69 * \code
70 * KLocale *myLocale = new KLocale("myapp", "ar", "eg");
71 * KCalendarSystem *myCalendar = KCalendarSystem::create(KLocale::IslamicCivilCalendar, myLocale);
72 * KLocalizedDate myDate(QDate(2010,1,1), myCalendar);
73 * \endcode
74 *
75 * In this case you are responsible for the memory management of the KLocale
76 * and KCalendarSystem. This allows you to reuse this calendar across multiple
77 * date instances without it being deleted under you. It also allows you to
78 * change any setting in the Locale and have it apply across all those date
79 * instances. @warning Don't try changing the Calendar System via your Locale
80 * instance, your KCalendarSystem instance will be deleted and all the dates
81 * will be invalid!
82 *
83 * @see
84 *
85 * @section formatting Date Formatting
86 *
87 * When you display dates or date components to users in a GUI, they will
88 * expect them to be displayed in their language and digit set following their
89 * local date formatting conventions. Directly displaying values returned by
90 * the normal date component methods such as day() will not conform to these
91 * expectations, so you need to use different methods to obtain the localized
92 * string form of the date or component.
93 *
94 * You can either format the entire date, or just a single component of the
95 * date such as the month or day.
96 *
97 * When formatting a full date, it is preferred to use one of the standard date
98 * formats defined in the Locale, although you can provide your own format in
99 * either the KDE, POSIX, or UNICODE standards.
100 *
101 * @see formatDate() formatDate()
102 *
103 * @section parsing Date Parsing
104 *
105 * Basic concepts on date parsing, then full details on KLocale::ReadDateFlags
106 * formats, definging your own date format strings, and setting how strictly
107 * the format is appplied.
108 *
109 * You can choose how strictly a date format is applied in parsing. Currently
110 * only liberal Parsing is supported.
111 *
112 * The KLocale::LiberalParsing mode applies the following rules:
113 *
114 * 1) You must supply a format and string containing at least one of the following combinations to
115 * create a valid date:
116 * @li a month and day of month
117 * @li a day of year
118 * @li a ISO week number and day of week
119 *
120 * 2) If a year number is not supplied then the current year will be assumed.
121 *
122 * 3) All date components must be separated by a non-numeric character.
123 *
124 * 4) The format is not applied strictly to the input string:
125 * @li extra whitespace is ignored
126 * @li leading 0's on numbers are ignored
127 * @li capitalisation of literals is ignored
128 *
129 * @see readDate()
130 *
131 * @section maths Date Maths
132 *
133 * A full set of date maths functions are provided which operate in a consistent
134 * manner, i.e. you can safely round-trip.
135 *
136 */
137
138class KDECORE_EXPORT KLocalizedDate
139{
140public:
141
142 /**
143 * Constructs a localized date with the given date.
144 *
145 * By default, uses the global Calendar System and Locale.
146 *
147 * If you pass in a custom Calendar System then you retain ownership of it
148 * and are responsible for deleting it. This allows you to reuse the same
149 * custom Calendar System for many localized date instances.
150 *
151 * See @ref custom for more details on using custom Calendar Systems.
152 *
153 * @param date the QDate to set the KLocalizedDate to, defaults to invalid date
154 * @param calendar the calendar system to use, defaults to the global
155 */
156 explicit KLocalizedDate(const QDate &date = QDate(), const KCalendarSystem *calendar = 0);
157
158 /**
159 * Constructs a localized date with the given year, month and day.
160 *
161 * By default, uses the global Calendar System and Locale.
162 *
163 * If you pass in a custom Calendar System then you retain ownership of it
164 * and are responsible for deleting it. This allows you to reuse the same
165 * custom Calendar System for many localized date instances.
166 *
167 * See @ref custom for more details on using custom Calendar Systems.
168 *
169 * @param year the year to set the KLocalizedDate to
170 * @param month the month to set the KLocalizedDate to
171 * @param day the day to set the KLocalizedDate to
172 * @param calendar the calendar system to use, defaults to the global
173 */
174 KLocalizedDate(int year, int month, int day, const KCalendarSystem *calendar = 0);
175
176 /**
177 * Copy constructor
178 *
179 * @param rhs the date to copy
180 */
181 KLocalizedDate(const KLocalizedDate &rhs);
182
183 /**
184 * Assignment operator
185 *
186 * @param rhs the date to assign
187 */
188 KLocalizedDate &operator=(const KLocalizedDate &rhs);
189
190 /**
191 * Assignment operator
192 *
193 * @param rhs the date to assign
194 */
195 KLocalizedDate &operator=(const QDate &rhs);
196
197 /**
198 * Destructor.
199 */
200 ~KLocalizedDate();
201
202 /**
203 * Set the Calendar System used for this date instance only.
204 *
205 * This method is mostly useful for when you quickly want to see what the
206 * currently set date would look like in a different Calendar System but
207 * using the same Locale.
208 *
209 * When the Calendar System is changed, a copy will be taken of the Locale
210 * previously used and this copy will be applied to the new Calendar System.
211 * Any changes to the old Locale settings, either the Global or a Custom
212 * Locale, will not be applied to this date instance.
213 *
214 * See @ref custom for more details on using custom Calendar Systems.
215 *
216 * @see KLocale::CalendarSystem
217 * @see calendarSystem()
218 * @param calendarSystem the Calendar System to use
219 */
220 void setCalendarSystem(KLocale::CalendarSystem calendarSystem);
221
222 /**
223 * Returns the Calendar System used by this localized date instance
224 *
225 * @see KLocale::CalendarSystem
226 * @see setCalendarSystem()
227 * @return the Calendar System currently used
228 */
229 KLocale::CalendarSystem calendarSystem();
230
231 /**
232 * Returns a pointer to the Calendar System object used by this date instance.
233 *
234 * Usually this will be the Global Calendar System, but this may have been
235 * changed.
236 *
237 * Normally you will not need to access this object unless the KLocalizedDate
238 * API does not provide the methods you require.
239 *
240 * @see KCalendarSystem
241 * @see calendarSystem
242 * @see setCalendarSystem
243 * @return the current calendar system instance
244 */
245 const KCalendarSystem *calendar() const;
246
247 /**
248 * Returns whether the date is null, i.e. invalid in any Calendar System.
249 *
250 * @see isValid
251 * @return @c true if the date is null, @c false otherwise
252 */
253 bool isNull() const;
254
255 /**
256 * Returns whether the date is valid in the current Calendar System.
257 *
258 * @see isNull
259 * @return @c true if the date is valid, @c false otherwise
260 */
261 bool isValid() const;
262
263 /**
264 * Set the date using a QDate.
265 *
266 * @param date the QDate to set to
267 * @return @c true if the date is valid, @c false otherwise
268 */
269 bool setDate(const QDate &date);
270
271 /**
272 * Set the date's year, month and day.
273 *
274 * The range of the year, month and day, and the validity of the date as a
275 * whole depends on which Calendar System is being used.
276 *
277 * @see getDate()
278 * @param year year number
279 * @param month month of year number
280 * @param day day of month
281 * @return @c true if the date is valid, @c false otherwise
282 */
283 bool setDate(int year, int month, int day);
284
285 /**
286 * Set the date using the year number and day of year number only.
287 *
288 * @see dayOfYear()
289 * @param year year
290 * @param dayOfYear day of year
291 * @return @c true if the date is valid, @c false otherwise
292 */
293 bool setDate(int year, int dayOfYear);
294
295 /**
296 * Set the date using the era, year in era number, month and day
297 *
298 * @see eraName()
299 * @see yearInEra()
300 * @param eraName Era string
301 * @param yearInEra Year In Era number
302 * @param month Month number
303 * @param day Day Of Month number
304 * @return @c true if the date is valid, @c false otherwise
305 */
306 bool setDate(QString eraName, int yearInEra, int month, int day);
307
308 /**
309 * Set the date using the year, week and day of week.
310 *
311 * Currently only the ISO Week Number System is supported.
312 *
313 * @see week()
314 * @see dayOfWeek()
315 * @param weekNumberSystem the week number system to use
316 * @param year year
317 * @param weekOfYear week of year
318 * @param dayOfWeek day of week Mon..Sun (1..7)
319 * @return @c true if the date is valid, @c false otherwise
320 */
321 bool setDate(KLocale::WeekNumberSystem weekNumberSystem, int year, int weekOfYear, int dayOfWeek);
322
323 /**
324 * Set the date to today's date
325 *
326 * @see currentDate()
327 * @return @c true if the date is valid, @c false otherwise
328 */
329 bool setCurrentDate();
330
331 /**
332 * Returns a KLocalizedDate set to today's date in the Global Locale and
333 * Calendar System.
334 *
335 * @see setCurrentDate()
336 * @return today's localized date
337 */
338 static KLocalizedDate currentDate();
339
340 /**
341 * Returns a KLocalizedDate set the required date in the Global Locale and
342 * Calendar System.
343 *
344 * @param date the date to set to
345 * @return a localized date
346 */
347 static KLocalizedDate fromDate(const QDate &date);
348
349 /**
350 * Returns a KLocalizedDate set the required Julian Day number in the Global
351 * Locale and Calendar System.
352 *
353 * @see toJulianDay()
354 * @param jd the Julian Day number to set to
355 * @return a localized date
356 */
357 static KLocalizedDate fromJulianDay(int jd);
358
359 /**
360 * Returns the currently set date as a Julian Day number
361 *
362 * @see fromJulianDay()
363 * @return the currently set date as a Julian Day number
364 */
365 int toJulianDay() const;
366
367 /**
368 * Returns the currently set date as a QDate
369 *
370 * @return the currently set date as a QDate
371 */
372 QDate date() const;
373
374 /**
375 * Returns the year, month and day portion of the date in the current
376 * Calendar System.
377 *
378 * See @ref formatting for why you should never display this value.
379 *
380 * @see setDate()
381 * @see formatDate()
382 * @param year year number returned in this variable
383 * @param month month number returned in this variable
384 * @param day day of month returned in this variable
385 */
386 void getDate(int *year, int *month, int *day) const;
387
388 /**
389 * Returns the year portion of the date in the current calendar system
390 *
391 * See @ref formatting for why you should never display this value.
392 *
393 * @see formatDate()
394 * @return the localized year number
395 */
396 int year() const;
397
398 /**
399 * Returns the month portion of the date in the current calendar system
400 *
401 * See @ref formatting for why you should never display this value.
402 *
403 * @see formatDate()
404 * @return the localized month number, 0 if date is invalid
405 */
406 int month() const;
407
408 /**
409 * Returns the day portion of the date in the current calendar system
410 *
411 * See @ref formatting for why you should never display this value.
412 *
413 * @see formatDate()
414 * @return the localized day number, 0 if date is invalid
415 */
416 int day() const;
417
418 /**
419 * Returns the Era Name portion of the date in the current calendar system,
420 * for example "AD" or "Anno Domini" for the Gregorian calendar and Christian Era.
421 *
422 * See @ref formatting for more details on Date Formatting.
423 *
424 * @see formatDate()
425 * @return the localized era name, empty string if date is invalid
426 */
427 QString eraName() const;
428
429 /**
430 * Returns the Era Year portion of the date in the current
431 * calendar system, for example "2000 AD" or "Heisei 22".
432 *
433 * See @ref formatting for more details on Date Formatting.
434 *
435 * @see formatDate()
436 * @return the localized era year string, empty string if date is invalid
437 */
438 QString eraYear() const;
439
440 /**
441 * Returns the Year In Era portion of the date in the current calendar
442 * system, for example 1 for "1 BC".
443 *
444 * See @ref formatting for why you should never display this value.
445 *
446 * @see formatDate()
447 * @see formatYearInEra()
448 * @return the localized Year In Era number, -1 if date is invalid
449 */
450 int yearInEra() const;
451
452 /**
453 * Returns the day number of year for the date
454 *
455 * The days are numbered 1..daysInYear()
456 *
457 * See @ref formatting for why you should never display this value.
458 *
459 * @see formatDate()
460 * @return day of year number, -1 if date not valid
461 */
462 int dayOfYear() const;
463
464 /**
465 * Returns the weekday number for the date
466 *
467 * The weekdays are numbered 1..7 for Monday..Sunday.
468 *
469 * This value is @em not affected by the value of KLocale::weekStartDay()
470 *
471 * See @ref formatting for why you should never display this value.
472 *
473 * @see formatDate()
474 * @return day of week number, -1 if date not valid
475 */
476 int dayOfWeek() const;
477
478 /**
479 * Returns the localized Week Number for the date.
480 *
481 * See @ref formatting for why you should never display this value.
482 *
483 * This may be ISO, US, or any other supported week numbering scheme. If
484 * you specifically require the ISO Week or any other scheme, you should use
485 * the week(KLocale::WeekNumberSystem) form.
486 *
487 * If the date falls in the last week of the previous year or the first
488 * week of the following year, then the yearNum returned will be set to the
489 * appropriate year.
490 *
491 * @see weeksInYear()
492 * @see formatDate()
493 * @param yearNum returns the year the date belongs to
494 * @return localized week number, -1 if input date invalid
495 */
496 int week(int *yearNum = 0) const;
497
498 /**
499 * Returns the Week Number for the date in the required Week Number System.
500 *
501 * See @ref formatting for why you should never display this value.
502 *
503 * Unless you want a specific Week Number System (e.g. ISO Week), you should
504 * use the localized Week Number form of week().
505 *
506 * If the date falls in the last week of the previous year or the first
507 * week of the following year, then the yearNum returned will be set to the
508 * appropriate year.
509 *
510 * Technically, the ISO Week Number only applies to the ISO/Gregorian Calendar
511 * System, but the same rules will be applied to the current Calendar System.
512 *
513 * @see weeksInYear()
514 * @see formatDate()
515 * @param weekNumberSystem the Week Number System to use
516 * @param yearNum returns the year the date belongs to
517 * @return week number, -1 if input date invalid
518 */
519 int week(KLocale::WeekNumberSystem weekNumberSystem, int *yearNum = 0) const;
520
521 /**
522 * Returns number of months in the year
523 *
524 * See @ref formatting for why you should never display this value.
525 *
526 * @see formatDate()
527 * @return number of months in the year, -1 if date invalid
528 */
529 int monthsInYear() const;
530
531 /**
532 * Returns the number of localized weeks in the currently set year.
533 *
534 * See @ref formatting for why you should never display this value.
535 *
536 * If you specifically require the number of ISO Weeks, you should use
537 * weeksInYear(KLocale::IsoWeekNumber)
538 *
539 * @see week()
540 * @see formatDate()
541 * @return number of weeks in the year, -1 if date invalid
542 */
543 int weeksInYear() const;
544
545 /**
546 * Returns the number of Weeks in the currently set year using the required
547 * Week Number System.
548 *
549 * See @ref formatting for why you should never display this value.
550 *
551 * Unless you specifically want a particular Week Number System (e.g. ISO Weeks)
552 * you should use the localized number of weeks provided by weeksInYear().
553 *
554 * @see week()
555 * @see formatDate()
556 * @param weekNumberSystem the week number system to use
557 * @return number of weeks in the year, -1 if date invalid
558 */
559 int weeksInYear(KLocale::WeekNumberSystem weekNumberSystem) const;
560
561 /**
562 * Returns the number of days in the year.
563 *
564 * For example, in the Gregorian calendar most years have 365 days but Leap
565 * Years have 366 years. Other Calendar Systems have different length years.
566 *
567 * See @ref formatting for why you should never display this value.
568 *
569 * @see formatDate()
570 * @return number of days in year, -1 if date invalid
571 */
572 int daysInYear() const;
573
574 /**
575 * Returns the number of days in the month.
576 *
577 * See @ref formatting for why you should never display this value.
578 *
579 * @see formatDate()
580 * @return number of days in month, -1 if date invalid
581 */
582 int daysInMonth() const;
583
584 /**
585 * Returns the number of days in the week.
586 *
587 * See @ref formatting for why you should never display this value.
588 *
589 * @see formatDate()
590 * @return number of days in week, -1 if date invalid
591 */
592 int daysInWeek() const;
593
594 /**
595 * Returns whether the currently set date falls in a Leap Year in the
596 * current Calendar System.
597 *
598 * @return true if the date falls in a leap year
599 */
600 bool isLeapYear() const;
601
602 /**
603 * Returns the Date as a localized string in the requested standard Locale
604 * format.
605 *
606 * See @ref formatting for more details on Date Formatting and valid Locale
607 * formats.
608 *
609 * @see formatDate()
610 * @param dateFormat the standard date format to use
611 * @return The date as a localized string
612 */
613 QString formatDate(KLocale::DateFormat dateFormat = KLocale::LongDate) const;
614
615 /**
616 * Returns the Date as a localized string in the requested format.
617 *
618 * See @ref formatting for more details on Date Formatting and valid format
619 * codes.
620 *
621 * Please use with care and only in situations where the standard Locale
622 * formats or the component format methods do not provide what you
623 * need. You should almost always translate your @p formatString as
624 * documented above. Using the standard DateFormat options instead would
625 * take care of the translation for you.
626 *
627 * The toFormat parameter is a good candidate to be made translatable,
628 * so that translators can adapt it to their language's convention.
629 * There should also be a context using the "kdedt-format" keyword (for
630 * automatic validation of translations) and stating the format's purpose:
631 * \code
632 * QDate reportDate;
633 * KGlobal::locale()->calendar()->setDate(reportDate, reportYear, reportMonth, 1);
634 * dateFormat = i18nc("(kdedt-format) Report month and year in report header", "%B %Y"));
635 * dateString = KGlobal::locale()->calendar()->formatDate(reportDate, dateFormat);
636 * \endcode
637 *
638 * The date format string can be defined using either the KDE, POSIX or the Qt
639 * subset of the UNICODE standards.
640 *
641 * The KDE standard closely follows the POSIX standard but with some exceptions.
642 * Always use the KDE standard within KDE, but where interaction is required with
643 * external POSIX compliant systems (e.g. Gnome, glibc, etc) the POSIX standard
644 * should be used. The UNICODE standard is provided for comaptability with QDate
645 * and so is not yet the full standard, only what Qt currently supports.
646 *
647 * Date format strings are made up of date components and string literals.
648 * Date components are prefixed by a % escape character and are made up of
649 * optional padding and case modifier flags, an optional width value, and a
650 * compulsary code for the actual date component:
651 * %[Flags][Width][Componant]
652 * e.g. %_^5Y
653 * No spaces are allowed.
654 *
655 * The Flags can modify the padding character and/or case of the Date Componant.
656 * The Flags are optional and may be combined and/or repeated in any order,
657 * in which case the last Padding Flag and last Case Flag will be the
658 * ones used. The Flags must be immediately after the % and before any Width.
659 *
660 * The Width can modify how wide the date Componant is padded to. The Width
661 * is an optional interger value and must be after any Flags but before the
662 * Componant. If the Width is less than the minimum defined for a Componant
663 * then the default minimum will be used instead.
664 *
665 * By default most numeric Date Componants are right-aligned with leading 0's.
666 *
667 * By default all string name fields are capital case and unpadded.
668 *
669 * The following Flags may be specified:
670 * @li - (hyphen) no padding (e.g. 1 Jan and "%-j" = "1")
671 * @li _ (underscore) pad with spaces (e.g. 1 Jan and "%-j" = " 1")
672 * @li 0 (zero) pad with 0's (e.g. 1 Jan and "%0j" = "001")
673 * @li ^ (caret) make uppercase (e.g. 1 Jan and "%^B" = "JANUARY")
674 * @li # (hash) invert case (e.g. 1 Jan and "%#B" = "???")
675 *
676 * The following Date Componants can be specified:
677 * @li %Y the year to 4 digits (e.g. "1984" for 1984, "0584" for 584, "0084" for 84)
678 * @li %C the 'century' portion of the year to 2 digits (e.g. "19" for 1984, "05" for 584, "00" for 84)
679 * @li %y the lower 2 digits of the year to 2 digits (e.g. "84" for 1984, "05" for 2005)
680 * @li %EY the full local era year (e.g. "2000 AD")
681 * @li %EC the era name short form (e.g. "AD")
682 * @li %Ey the year in era to 1 digit (e.g. 1 or 2000)
683 * @li %m the month number to 2 digits (January="01", December="12")
684 * @li %n the month number to 1 digit (January="1", December="12"), see notes!
685 * @li %d the day number of the month to 2 digits (e.g. "01" on the first of March)
686 * @li %e the day number of the month to 1 digit (e.g. "1" on the first of March)
687 * @li %B the month name long form (e.g. "January")
688 * @li %b the month name short form (e.g. "Jan" for January)
689 * @li %h the month name short form (e.g. "Jan" for January)
690 * @li %A the weekday name long form (e.g. "Wednesday" for Wednesday)
691 * @li %a the weekday name short form (e.g. "Wed" for Wednesday)
692 * @li %j the day of the year number to 3 digits (e.g. "001" for 1 Jan)
693 * @li %V the ISO week of the year number to 2 digits (e.g. "01" for ISO Week 1)
694 * @li %G the year number in long form of the ISO week of the year to 4 digits (e.g. "2004" for 1 Jan 2005)
695 * @li %g the year number in short form of the ISO week of the year to 2 digits (e.g. "04" for 1 Jan 2005)
696 * @li %u the day of the week number to 1 digit (e.g. "1" for Monday)
697 * @li %D the US short date format (e.g. "%m/%d/%y")
698 * @li %F the ISO short date format (e.g. "%Y-%m-%d")
699 * @li %x the KDE locale short date format
700 * @li %% the literal "%"
701 * @li %t a tab character
702 *
703 * Everything else in the format string will be taken as literal text.
704 *
705 * Examples:
706 * "%Y-%m-%d" = "2009-01-01"
707 * "%Y-%-m-%_4d" = "2009-1- 1"
708 *
709 * The following format codes behave differently in the KDE and POSIX standards
710 * @li %e in GNU/POSIX is space padded to 2 digits, in KDE is not padded
711 * @li %n in GNU/POSIX is newline, in KDE is short month number
712 *
713 * The following POSIX format codes are currently not supported:
714 * @li %U US week number
715 * @li %w US day of week
716 * @li %W US week number
717 * @li %O locale's alternative numeric symbols, in KDE is not supported
718 *
719 * %0 is not supported as the returned result is always in the locale's chosen numeric symbol digit set.
720 *
721 * @see formatDate()
722 * @param formatString the date format to use
723 * @param formatStandard the standard the @p dateFormat uses, defaults to KDE Standard
724 * @return The date as a localized string
725 */
726 QString formatDate(const QString &formatString,
727 KLocale::DateTimeFormatStandard formatStandard = KLocale::KdeFormat) const;
728
729 /**
730 * Returns a Date Component as a localized string in the requested format.
731 *
732 * See @ref formatting for more details on Date Formatting.
733 *
734 * Each format size may vary depending on Locale and Calendar System but will
735 * generally match the format description. Some formats may not be directly
736 * valid but a sensible value will always be returned.
737 *
738 * For example for 2010-01-01 the KLocale::Month with en_US Locale and Gregorian calendar may return:
739 * KLocale::ShortNumber = "1"
740 * KLocale::LongNumber = "01"
741 * KLocale::NarrowName = "J"
742 * KLocale::ShortName = "Jan"
743 * KLocale::LongName = "January"
744 *
745 * @see formatDate()
746 * @param component The date component to return
747 * @param format The format to return the @p component in
748 * @param weekNumberSystem To override the default Week Number System to use
749 * @return The string form of the date component
750 */
751 QString formatDate(KLocale::DateTimeComponent component,
752 KLocale::DateTimeComponentFormat format = KLocale::DefaultComponentFormat,
753 KLocale::WeekNumberSystem weekNumberSystem = KLocale::DefaultWeekNumber) const;
754
755 /**
756 * Converts a localized date string to a KLocalizedDate using either the
757 * Global Calendar System and Locale, or the provided Calendar System.
758 *
759 * See @ref parsing for more details on Date Parsing from strings.
760 *
761 * This method is more liberal and will return a valid date if the
762 * @p dateString matches any of the KLocale::ReadDateFlags formats
763 * for the Locale.
764 *
765 * If you require a certain KLocale::ReadDateFlags format or a customized
766 * format string, use one of the other readDate() methods.
767 *
768 * @param dateString the string to parse
769 * @param parseMode how strictly to apply the locale formats to the @p dateString
770 * @param calendar the Calendar System to use when parsing the date
771 * @return the localized date parsed from the string
772 */
773 static KLocalizedDate readDate(const QString &dateString,
774 KLocale::DateTimeParseMode parseMode = KLocale::LiberalParsing,
775 const KCalendarSystem *calendar = 0);
776
777 /**
778 * Converts a localized date string to a KLocalizedDate using either the
779 * Global Calendar System and Locale, or the provided Calendar System.
780 *
781 * See @ref parsing for more details on Date Parsing from strings.
782 *
783 * This method is stricter and will return a valid date only if the
784 * @p dateString matches one of the @p dateFlags formats requested.
785 *
786 * If you require any KLocale::ReadDateFlags format or a customized format
787 * string, use one of the other readDate() methods.
788 *
789 * @param dateString the string to parse
790 * @param formatFlags the locale format(s) to try parse the string with
791 * @param parseMode how strictly to apply the @p formatFlags to the @p dateString
792 * @param calendar the Calendar System to use when parsing the date
793 * @return the localized date parsed from the string
794 */
795 static KLocalizedDate readDate(const QString &dateString,
796 KLocale::ReadDateFlags formatFlags,
797 KLocale::DateTimeParseMode parseMode = KLocale::LiberalParsing,
798 const KCalendarSystem *calendar = 0);
799
800 /**
801 * Converts a localized date string to a KLocalizedDate using either the
802 * Global Calendar System and Locale, or the provided Calendar System.
803 *
804 * See @ref parsing for more details on Date Parsing from strings.
805 *
806 * This method allows you to define your own date format to parse the date
807 * string with.
808 *
809 * If you require one of the standard any KLocale::ReadDateFlags formats
810 * then use one of the other readDate() methods.
811 *
812 * @param dateString the string to parse
813 * @param dateFormat the date format to try parse the string with
814 * @param parseMode how strictly to apply the @p dateFormat to the @p dateString
815 * @param formatStandard the standard the @p dateFormat format uses
816 * @param calendar the Calendar System to use when parsing the date
817 * @return the localized date parsed from the string
818 */
819 static KLocalizedDate readDate(const QString &dateString,
820 const QString &dateFormat,
821 KLocale::DateTimeParseMode parseMode = KLocale::LiberalParsing,
822 KLocale::DateTimeFormatStandard formatStandard = KLocale::KdeFormat,
823 const KCalendarSystem *calendar = 0);
824
825 /**
826 * Returns a KLocalizedDate containing a date @p years years later.
827 *
828 * @see addYearsTo()
829 * @see addMonths() addDays()
830 * @see dateDifference() yearsDifference()
831 * @param years The number of years to add
832 * @return The new date, null date if any errors
833 */
834 KLocalizedDate addYears(int years) const;
835
836 /**
837 * Add years onto this date instance.
838 *
839 * If the result of the addition is invalid in the current Calendar System
840 * then the date will become invalid.
841 *
842 * @see addYears()
843 * @see addMonthsTo() addDaysTo()
844 * @see dateDifference() yearsDifference()
845 * @param years The number of years to add
846 * @return if the resulting date is valid
847 */
848 bool addYearsTo(int years);
849
850 /**
851 * Returns a KLocalizedDate containing a date @p months months later.
852 *
853 * @see addMonthsTo()
854 * @see addYears() addDays()
855 * @see dateDifference() yearsDifference()
856 * @param months number of months to add
857 * @return The new date, null date if any errors
858 */
859 KLocalizedDate addMonths(int months) const;
860
861 /**
862 * Add months onto this date instance.
863 *
864 * If the result of the addition is invalid in the current Calendar System
865 * then the date will become invalid.
866 *
867 * @see addMonths()
868 * @see addYearsTo() addDaysTo()
869 * @see dateDifference() yearsDifference()
870 * @param months The number of months to add
871 * @return if the resulting date is valid
872 */
873 bool addMonthsTo(int months);
874
875 /**
876 * Returns a KLocalizedDate containing a date @p days days later.
877 *
878 * @see addDaysTo()
879 * @see addYears() addMonths()
880 * @see dateDifference() yearsDifference()
881 * @param days number of days to add
882 * @return The new date, null date if any errors
883 */
884 KLocalizedDate addDays(int days) const;
885
886 /**
887 * Add days onto this date instance.
888 *
889 * If the result of the addition is invalid in the current Calendar System
890 * then the date will become invalid.
891 *
892 * @see addDays()
893 * @see addYearsTo(), addMonthsTo()
894 * @see dateDifference() yearsDifference()
895 * @param days The number of days to add
896 * @return if the resulting date is valid
897 */
898 bool addDaysTo(int days);
899
900 /**
901 * Returns the difference between this and another date in years, months and days
902 * in the current Calendar System.
903 *
904 * The difference is always calculated from the earlier date to the later
905 * date in year, month and day order, with the @p direction parameter
906 * indicating which direction the difference is applied from this date.
907 * In other words, this difference can be added onto the earlier date in
908 * year, month, day order to reach the later date.
909 *
910 * For example, the difference between 2010-06-10 and 2012-09-5 is 2 years,
911 * 2 months and 26 days. Note that the difference between two last days of
912 * the month is always 1 month, e.g. 2010-01-31 to 2010-02-28 is 1 month
913 * not 28 days.
914 *
915 * @see addYears() addMonths() addDays()
916 * @see yearsDifference() monthsDifference() daysDifference()
917 * @param toDate The date to end at
918 * @param yearsDiff Returns number of years difference
919 * @param monthsDiff Returns number of months difference
920 * @param daysDiff Returns number of days difference
921 * @param direction Returns direction of difference, 1 if this Date <= toDate, -1 otherwise
922 */
923 void dateDifference(const KLocalizedDate &toDate,
924 int *yearsDiff, int *monthsDiff, int *daysDiff, int *direction) const;
925
926 /**
927 * Returns the difference between this and another date in years, months and days
928 * in the current Calendar System.
929 *
930 * The difference is always calculated from the earlier date to the later
931 * date in year, month and day order, with the @p direction parameter
932 * indicating which direction the difference is applied from this date.
933 * In other words, this difference can be added onto the earlier date in
934 * year, month, day order to reach the later date.
935 *
936 * For example, the difference between 2010-06-10 and 2012-09-5 is 2 years,
937 * 2 months and 26 days. Note that the difference between two last days of
938 * the month is always 1 month, e.g. 2010-01-31 to 2010-02-28 is 1 month
939 * not 28 days.
940 *
941 * @see addYears() addMonths() addDays()
942 * @see yearsDifference() monthsDifference() daysDifference()
943 * @param toDate The date to end at
944 * @param yearsDiff Returns number of years difference
945 * @param monthsDiff Returns number of months difference
946 * @param daysDiff Returns number of days difference
947 * @param direction Returns direction of difference, 1 if this Date <= toDate, -1 otherwise
948 */
949 void dateDifference(const QDate &toDate,
950 int *yearsDiff, int *monthsDiff, int *daysDiff, int *direction) const;
951
952 /**
953 * Returns the difference between this and another date in completed calendar years
954 * in the current Calendar System.
955 *
956 * The returned value will be negative if @p toDate < this date.
957 *
958 * For example, the difference between 2010-06-10 and 2012-09-5 is 2 years.
959 *
960 * @see addYears()
961 * @see dateDifference() monthsDifference() daysDifference()
962 * @param toDate The date to end at
963 * @return The number of years difference
964 */
965 int yearsDifference(const KLocalizedDate &toDate) const;
966
967 /**
968 * Returns the difference between this and another date in completed calendar years
969 * in the current Calendar System.
970 *
971 * The returned value will be negative if @p toDate < this date.
972 *
973 * For example, the difference between 2010-06-10 and 2012-09-5 is 2 years.
974 *
975 * @see addYears()
976 * @see dateDifference() monthsDifference() daysDifference()
977 * @param toDate The date to end at
978 * @return The number of years difference
979 */
980 int yearsDifference(const QDate &toDate) const;
981
982 /**
983 * Returns the difference between this and another date in completed calendar months
984 * in the current Calendar System.
985 *
986 * The returned value will be negative if @p toDate < this date.
987 *
988 * For example, the difference between 2010-06-10 and 2012-09-5 is 26 months.
989 * Note that the difference between two last days of the month is always 1
990 * month, e.g. 2010-01-31 to 2010-02-28 is 1 month not 28 days.
991 *
992 * @see addMonths()
993 * @see dateDifference() yearsDifference() daysDifference()
994 * @param toDate The date to end at
995 * @return The number of months difference
996 */
997 int monthsDifference(const KLocalizedDate &toDate) const;
998
999 /**
1000 * Returns the difference between this and another date in completed calendar months
1001 * in the current Calendar System.
1002 *
1003 * The returned value will be negative if @p toDate < this date.
1004 *
1005 * For example, the difference between 2010-06-10 and 2012-09-5 is 26 months.
1006 * Note that the difference between two last days of the month is always 1
1007 * month, e.g. 2010-01-31 to 2010-02-28 is 1 month not 28 days.
1008 *
1009 * @see addMonths()
1010 * @see dateDifference() yearsDifference() daysDifference()
1011 * @param toDate The date to end at
1012 * @return The number of months difference
1013 */
1014 int monthsDifference(const QDate &toDate) const;
1015
1016 /**
1017 * Returns the difference between this and another date in days
1018 * The returned value will be negative if @p toDate < this date.
1019 *
1020 * @see addDays()
1021 * @see dateDifference() yearsDifference() monthsDifference()
1022 * @param toDate The date to end at
1023 * @return The number of days difference
1024 */
1025 int daysDifference(const KLocalizedDate &toDate) const;
1026
1027 /**
1028 * Returns the difference between this and another date in days
1029 * The returned value will be negative if @p toDate < this date.
1030 *
1031 * @see addDays()
1032 * @see dateDifference() yearsDifference() monthsDifference()
1033 * @param toDate The date to end at
1034 * @return The number of days difference
1035 */
1036 int daysDifference(const QDate &toDate) const;
1037
1038 /**
1039 * Returns a KLocalizedDate containing the first day of the currently set year
1040 *
1041 * @see lastDayOfYear()
1042 * @return The first day of the year
1043 */
1044 KLocalizedDate firstDayOfYear() const;
1045
1046 /**
1047 * Returns a KLocalizedDate containing the last day of the currently set year
1048 *
1049 * @see firstDayOfYear()
1050 * @return The last day of the year
1051 */
1052 KLocalizedDate lastDayOfYear() const;
1053
1054 /**
1055 * Returns a KLocalizedDate containing the first day of the currently set month
1056 *
1057 * @see lastDayOfMonth()
1058 * @return The first day of the month
1059 */
1060 KLocalizedDate firstDayOfMonth() const;
1061
1062 /**
1063 * Returns a KLocalizedDate containing the last day of the currently set month
1064 *
1065 * @see firstDayOfMonth()
1066 * @return The last day of the month
1067 */
1068 KLocalizedDate lastDayOfMonth() const;
1069
1070 /**
1071 * KLocalizedDate equality operator
1072 *
1073 * @param other the date to compare
1074 */
1075 bool operator==(const KLocalizedDate &other) const;
1076
1077 /**
1078 * QDate equality operator
1079 *
1080 * @param other the date to compare
1081 */
1082 bool operator==(const QDate &other) const;
1083
1084 /**
1085 * KLocalizedDate inequality operator
1086 *
1087 * @param other the date to compare
1088 */
1089 bool operator!=(const KLocalizedDate &other) const;
1090
1091 /**
1092 * QDate inequality operator
1093 *
1094 * @param other the date to compare
1095 */
1096 bool operator!=(const QDate &other) const;
1097
1098 /**
1099 * KLocalizedDate less than operator
1100 *
1101 * @param other the date to compare
1102 */
1103 bool operator<(const KLocalizedDate &other) const;
1104
1105 /**
1106 * QDate less than operator
1107 *
1108 * @param other the date to compare
1109 */
1110 bool operator<(const QDate &other) const;
1111
1112 /**
1113 * KLocalizedDate less than or equal to operator
1114 *
1115 * @param other the date to compare
1116 */
1117 bool operator<=(const KLocalizedDate &other) const;
1118
1119 /**
1120 * QDate less than or equal to operator
1121 *
1122 * @param other the date to compare
1123 */
1124 bool operator<=(const QDate &other) const;
1125
1126 /**
1127 * KLocalizedDate greater than operator
1128 *
1129 * @param other the date to compare
1130 */
1131 bool operator>(const KLocalizedDate &other) const;
1132
1133 /**
1134 * QDate greater than operator
1135 *
1136 * @param other the date to compare
1137 */
1138 bool operator>(const QDate &other) const;
1139
1140 /**
1141 * KLocalizedDate greater than or equal to operator
1142 *
1143 * @param other the date to compare
1144 */
1145 bool operator>=(const KLocalizedDate &other) const;
1146
1147 /**
1148 * QDate greater than or equal to operator
1149 *
1150 * @param other the date to compare
1151 */
1152 bool operator>=(const QDate &other) const;
1153
1154private:
1155
1156 friend QDataStream KDECORE_EXPORT &operator<<(QDataStream &out, const KLocalizedDate &date);
1157 friend QDataStream KDECORE_EXPORT &operator>>(QDataStream &in, KLocalizedDate &date);
1158 friend QDebug KDECORE_EXPORT operator<<(QDebug, const KLocalizedDate &);
1159
1160 QSharedDataPointer<KLocalizedDatePrivate> d;
1161};
1162
1163Q_DECLARE_METATYPE(KLocalizedDate)
1164
1165/**
1166 * Data stream output operator
1167 *
1168 * @param out the datastream to write to
1169 * @param date the date to write to the stream
1170 */
1171QDataStream KDECORE_EXPORT &operator<<(QDataStream &out, const KLocalizedDate &date);
1172
1173/**
1174 * Data stream input operator
1175 *
1176 * @param in the datastream to read from
1177 * @param date the date to read from the stream
1178 */
1179QDataStream KDECORE_EXPORT &operator>>(QDataStream &in, KLocalizedDate &date);
1180
1181/**
1182 * Debug stream output operator
1183 *
1184 * @param debug the debug datastream to write to
1185 * @param date the date to write to the stream
1186 */
1187QDebug KDECORE_EXPORT operator<<(QDebug debug, const KLocalizedDate &date);
1188
1189#endif // KLOCALIZEDDATE_H
1190