Warning: That file was not part of the compilation database. It may have many parsing errors.

1/*
2 Copyright (c) 2002 Carlos Moro <cfmoro@correo.uniovi.es>
3 Copyright (c) 2002-2003 Hans Petter Bieker <bieker@kde.org>
4 Copyright 2007, 2009, 2010 John Layt <john@layt.net>
5
6 This library is free software; you can redistribute it and/or
7 modify it under the terms of the GNU Library General Public
8 License as published by the Free Software Foundation; either
9 version 2 of the License, or (at your option) any later version.
10
11 This library is distributed in the hope that it will be useful,
12 but WITHOUT ANY WARRANTY; without even the implied warranty of
13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 Library General Public License for more details.
15
16 You should have received a copy of the GNU Library General Public License
17 along with this library; see the file COPYING.LIB. If not, write to
18 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
19 Boston, MA 02110-1301, USA.
20*/
21
22#ifndef KCALENDARSYSTEM_H
23#define KCALENDARSYSTEM_H
24
25#include <kdecore_export.h>
26#include "klocale.h" // needed for enums
27#include "kglobal.h"
28
29#include <QtCore/QStringList>
30#include <QtCore/QDate>
31
32class KCalendarSystemPrivate;
33class KCalendarEra;
34
35/**
36 * KCalendarSystem abstract base class, provides support for local Calendar Systems in KDE
37 *
38 * Derived classes must be created through the create() static method
39 */
40class KDECORE_EXPORT KCalendarSystem
41{
42public:
43
44 /**
45 * Format for returned year number / month number / day number as string.
46 */
47 enum StringFormat {
48 ShortFormat, /**< Short string format, e.g. 2000 = "00" or 6 = "6" */
49 LongFormat /**< Long string format, e.g. 2000 = "2000" or 6 = "06" */
50 };
51
52 /**
53 * Format for returned month / day name.
54 */
55 enum MonthNameFormat {
56 ShortName, /**< Short name format, e.g. "Dec" */
57 LongName, /**< Long name format, e.g. "December" */
58 ShortNamePossessive, /**< Short name possessive format, e.g. "of Dec" */
59 LongNamePossessive, /**< Long name possessive format, e.g. "of December" */
60 NarrowName /**< Narrow name format, e.g. "D". @since 4.7 */
61 };
62
63 /**
64 * Format for returned month / day name.
65 */
66 enum WeekDayNameFormat {
67 ShortDayName, /**< Short name format, e.g. "Fri" */
68 LongDayName, /**< Long name format, e.g. "Friday" */
69 NarrowDayName /**< Narrow name format, e.g. "F". @since 4.7 */
70 };
71
72 //KDE5 remove
73 /**
74 * @deprecated use create(KLocale::CalendarSystem, KLocale) instead
75 *
76 * Creates specific calendar type
77 *
78 * @param calType string identification of the specific calendar type
79 * to be constructed
80 * @param locale locale to use for translations. The global locale is used if null.
81 * @return a KCalendarSystem object
82 */
83 KDE_DEPRECATED static KCalendarSystem *create(const QString & calType = QLatin1String("gregorian"),
84 const KLocale * locale = 0);
85
86 //KDE5 remove
87 /**
88 * @deprecated use create(KLocale::CalendarSystem, KSharedConfig, KLocale) instead
89 *
90 * @since 4.5
91 *
92 * Creates specific calendar type
93 *
94 * @param calType string identification of the specific calendar type to be constructed
95 * @param config a configuration file with a 'KCalendarSystem %calendarType' group detailing
96 * locale-related preferences (such as era options). The global config is used
97 if null.
98 * @param locale locale to use for translations. The global locale is used if null.
99 * @return a KCalendarSystem object
100 */
101 KDE_DEPRECATED static KCalendarSystem *create(const QString & calType, KSharedConfig::Ptr config,
102 const KLocale * locale = 0);
103
104 //KDE5 add default value to calendarSystem
105 /**
106 * @since 4.6
107 *
108 * Creates a KCalendarSystem object for the required Calendar System
109 *
110 * @param calendarSystem the Calendar System to create, defaults to QDate compatible
111 * @param locale locale to use for translations. The global locale is used if null.
112 * @return a KCalendarSystem object
113 */
114 static KCalendarSystem *create(KLocale::CalendarSystem calendarSystem,
115 const KLocale *locale = 0);
116
117 /**
118 * @since 4.6
119 *
120 * Creates a KCalendarSystem object for the required Calendar System
121 *
122 * @param calendarSystem the Calendar System to create
123 * @param config a configuration file with a 'KCalendarSystem %calendarType' group detailing
124 * locale-related preferences (such as era options). The global config is used
125 if null.
126 * @param locale locale to use for translations. The global locale is used if null.
127 * @return a KCalendarSystem object
128 */
129 static KCalendarSystem *create(KLocale::CalendarSystem calendarSystem, KSharedConfig::Ptr config,
130 const KLocale *locale = 0);
131
132 //KDE5 remove
133 /**
134 * @deprecated use calendarSystemsList() instead
135 *
136 * Gets a list of names of supported calendar systems.
137 *
138 * @return list of names
139 */
140 KDE_DEPRECATED static QStringList calendarSystems();
141
142 /**
143 * @since 4.6
144 *
145 * Returns the list of currently supported Calendar Systems
146 *
147 * @return list of Calendar Systems
148 */
149 static QList<KLocale::CalendarSystem> calendarSystemsList();
150
151 //KDE5 remove
152 /**
153 * @deprecated use calendarLabel( KLocale::CalendarSystem ) instead
154 *
155 * Returns a typographically correct and translated label to display for
156 * the calendar system type. Use with calendarSystems() to neatly
157 * format labels to display on combo widget of available calendar systems.
158 *
159 * @param calendarType the specific calendar type to return the label for
160 *
161 * @return label for calendar
162 */
163 KDE_DEPRECATED static QString calendarLabel(const QString &calendarType);
164
165 /**
166 * @since 4.6
167 *
168 * Returns a localized label to display for the required Calendar System type.
169 *
170 * Use with calendarSystemsList() to populate selection lists of available
171 * calendar systems.
172 *
173 * @param calendarSystem the specific calendar type to return the label for
174 * @param locale the locale to use for the label, defaults to global
175 * @return label for calendar
176 */
177 static QString calendarLabel(KLocale::CalendarSystem calendarSystem, const KLocale *locale = KGlobal::locale());
178
179 //KDE5 Remove
180 /**
181 * @deprecated use calendarSystem(const QString &calendarType) instead
182 * @since 4.6
183 *
184 * Returns the Calendar System enum value for a given Calendar Type,
185 * e.g. KLocale::QDateCalendar for "gregorian"
186 *
187 * @param calendarType the calendar type to convert
188 * @return calendar system for calendar type
189 */
190 KDE_DEPRECATED static KLocale::CalendarSystem calendarSystemForCalendarType(const QString &calendarType);
191
192 //KDE5 Remove
193 /**
194 * @since 4.7
195 *
196 * Returns the Calendar System enum value for a given Calendar Type,
197 * e.g. KLocale::QDateCalendar for "gregorian"
198 *
199 * @param calendarType the calendar type to convert
200 * @return calendar system for calendar type
201 */
202 static KLocale::CalendarSystem calendarSystem(const QString &calendarType);
203
204 //KDE5 remove
205 /**
206 * @since 4.7
207 *
208 * Returns the deprecated Calendar Type for a given Calendar System enum value,
209 * e.g. "gregorian" for KLocale::QDateCalendar
210 *
211 * @param calendarSystem the calendar system to convert
212 * @return calendar type for calendar system
213 */
214 static QString calendarType(KLocale::CalendarSystem calendarSystem);
215
216 /**
217 * Constructor of abstract calendar class. This will be called by derived classes.
218 *
219 * @param locale locale to use for translations. The global locale is used if null.
220 */
221 explicit KCalendarSystem(const KLocale *locale = 0);
222
223 /**
224 * Constructor of abstract calendar class. This will be called by derived classes.
225 *
226 * @param config a configuration file with a 'KCalendarSystem %calendarName' group detailing
227 * locale-related preferences (such as era options). The global config is used
228 if null.
229 * @param locale locale to use for translations. The global locale is used if null.
230 */
231 explicit KCalendarSystem(const KSharedConfig::Ptr config, const KLocale *locale = 0);
232
233 /**
234 * Destructor.
235 */
236 virtual ~KCalendarSystem();
237
238 /**
239 * @deprecated use calendarSystem() instead
240 *
241 * Returns the calendar system type.
242 *
243 * @return type of calendar system
244 */
245 KDE_DEPRECATED virtual QString calendarType() const = 0;
246
247 //KDE5 make virtual?
248 /**
249 * @since 4.6
250 *
251 * Returns the Calendar System type of the KCalendarSystem object
252 *
253 * @return type of calendar system
254 */
255 KLocale::CalendarSystem calendarSystem() const;
256
257 //KDE5 make virtual?
258 /**
259 * @since 4.6
260 *
261 * Returns a localized label to display for the current Calendar System type.
262 *
263 * @return localized label for this Calendar System
264 */
265 QString calendarLabel() const;
266
267 /**
268 * Returns a QDate holding the epoch of the calendar system. Usually YMD
269 * of 1/1/1, access the returned QDates method toJulianDay() if you
270 * require the actual Julian day number. Note: a particular calendar
271 * system implementation may not include the epoch in its supported range,
272 * or the calendar system may be proleptic in which case it supports dates
273 * before the epoch.
274 *
275 * @see KCalendarSystem::earliestValidDate
276 * @see KCalendarSystem::latestValidDate
277 * @see KCalendarSystem::isProleptic
278 * @see KCalendarSystem::isValid
279 *
280 * @return epoch of calendar system
281 */
282 virtual QDate epoch() const;
283
284 /**
285 * Returns the earliest date valid in this calendar system implementation.
286 *
287 * If the calendar system is proleptic then this may be before epoch.
288 *
289 * @see KCalendarSystem::epoch
290 * @see KCalendarSystem::latestValidDate
291 *
292 * @return date the earliest valid date
293 */
294 virtual QDate earliestValidDate() const;
295
296 /**
297 * Returns the latest date valid in this calendar system implementation.
298 *
299 * @see KCalendarSystem::epoch
300 * @see KCalendarSystem::earliestValidDate
301 *
302 * @return date the latest valid date
303 */
304 virtual QDate latestValidDate() const;
305
306 /**
307 * Returns whether a given date is valid in this calendar system.
308 *
309 * @param year the year portion of the date to check
310 * @param month the month portion of the date to check
311 * @param day the day portion of the date to check
312 * @return @c true if the date is valid, @c false otherwise
313 */
314 virtual bool isValid(int year, int month, int day) const = 0;
315
316 //KDE5 make virtual?
317 /**
318 * @since 4.4
319 *
320 * Returns whether a given date is valid in this calendar system.
321 *
322 * @param year the year portion of the date to check
323 * @param dayOfYear the day of year portion of the date to check
324 * @return @c true if the date is valid, @c false otherwise
325 */
326 bool isValid(int year, int dayOfYear) const;
327
328 //KDE5 make virtual?
329 /**
330 * @since 4.5
331 *
332 * Returns whether a given date is valid in this calendar system.
333 *
334 * @param eraName the Era Name portion of the date to check
335 * @param yearInEra the Year In Era portion of the date to check
336 * @param month the Month portion of the date to check
337 * @param day the Day portion of the date to check
338 * @return @c true if the date is valid, @c false otherwise
339 */
340 bool isValid(const QString &eraName, int yearInEra, int month, int day) const;
341
342 //KDE5 make virtual?
343 /**
344 * @since 4.4
345 *
346 * Returns whether a given date is valid in this calendar system.
347 *
348 * @param year the year portion of the date to check
349 * @param isoWeekNumber the ISO week portion of the date to check
350 * @param dayOfIsoWeek the day of week portion of the date to check
351 * @return @c true if the date is valid, @c false otherwise
352 */
353 bool isValidIsoWeekDate(int year, int isoWeekNumber, int dayOfIsoWeek) const;
354
355 /**
356 * Returns whether a given date is valid in this calendar system.
357 *
358 * @param date the date to check
359 * @return @c true if the date is valid, @c false otherwise
360 */
361 virtual bool isValid(const QDate &date) const;
362
363 /**
364 * Changes the date's year, month and day. The range of the year, month
365 * and day depends on which calendar is being used. All years entered
366 * are treated literally, i.e. no Y2K translation is applied to years
367 * entered in the range 00 to 99. Replaces setYMD.
368 *
369 * @param date date to change
370 * @param year year
371 * @param month month number
372 * @param day day of month
373 * @return @c true if the date is valid, @c false otherwise
374 */
375 virtual bool setDate(QDate &date, int year, int month, int day) const;
376
377 //KDE5 make virtual?
378 /**
379 * @since 4.4
380 *
381 * Set a date using the year number and day of year number only.
382 *
383 * @param date date to change
384 * @param year year
385 * @param dayOfYear day of year
386 * @return @c true if the date is valid, @c false otherwise
387 */
388 bool setDate(QDate &date, int year, int dayOfYear) const;
389
390 //KDE5 make virtual?
391 /**
392 * @since 4.5
393 *
394 * Set a date using the era, year in era number, month and day
395 *
396 * @param date date to change
397 * @param eraName Era string
398 * @param yearInEra Year In Era number
399 * @param month Month number
400 * @param day Day Of Month number
401 * @return @c true if the date is valid, @c false otherwise
402 */
403 bool setDate(QDate &date, QString eraName, int yearInEra, int month, int day) const;
404
405 //KDE5 make virtual?
406 /**
407 * @since 4.4
408 *
409 * Set a date using the year number, ISO week number and day of week number.
410 *
411 * @param date date to change
412 * @param year year
413 * @param isoWeekNumber ISO week of year
414 * @param dayOfIsoWeek day of week Mon..Sun (1..7)
415 * @return @c true if the date is valid, @c false otherwise
416 */
417 bool setDateIsoWeek(QDate &date, int year, int isoWeekNumber, int dayOfIsoWeek) const;
418
419 /**
420 * @deprecated Use setDate() instead
421 *
422 * Some implementations reject year range 00 to 99, but extended date
423 * ranges now require these to be accepted. Equivalent in QDate is
424 * obsoleted.
425 *
426 * Changes the date's year, month and day. The range of the year, month
427 * and day depends on which calendar is being used.
428 *
429 * @param date Date to change
430 * @param y Year
431 * @param m Month number
432 * @param d Day of month
433 * @return true if the date is valid; otherwise returns false.
434 */
435 KDE_DEPRECATED virtual bool setYMD(QDate &date, int y, int m, int d) const;
436
437 //KDE5 make virtual?
438 /**
439 * @since 4.5
440 *
441 * Returns the year, month and day portion of a given date in the current calendar system
442 *
443 * @param date date to get year, month and day for
444 * @param year year number returned in this variable
445 * @param month month number returned in this variable
446 * @param day day of month returned in this variable
447 */
448 void getDate(const QDate date, int *year, int *month, int *day) const;
449
450 /**
451 * Returns the year portion of a given date in the current calendar system
452 *
453 * @param date date to return year for
454 * @return year, 0 if input date is invalid
455 */
456 virtual int year(const QDate &date) const;
457
458 /**
459 * Returns the month portion of a given date in the current calendar system
460 *
461 * @param date date to return month for
462 * @return month of year, 0 if input date is invalid
463 */
464 virtual int month(const QDate &date) const;
465
466 /**
467 * Returns the day portion of a given date in the current calendar system
468 *
469 * @param date date to return day for
470 * @return day of the month, 0 if input date is invalid
471 */
472 virtual int day(const QDate &date) const;
473
474 //KDE5 make virtual?
475 /**
476 * @since 4.5
477 *
478 * Returns the Era Name portion of a given date in the current calendar system,
479 * for example "AD" or "Anno Domini" for the Gregorian calendar and Christian Era.
480 *
481 * @param date date to return Era Name for
482 * @param format format to return, either short or long
483 * @return era name, empty string if input date is invalid
484 */
485 QString eraName(const QDate &date, StringFormat format = ShortFormat) const;
486
487 //KDE5 make virtual?
488 /**
489 * @since 4.5
490 *
491 * Returns the Era Year portion of a given date in the current
492 * calendar system, for example "2000 AD" or "Heisei 22".
493 *
494 * @param date date to return Era Year for
495 * @param format format to return, either short or long
496 * @return era name, empty string if input date is invalid
497 */
498 QString eraYear(const QDate &date, StringFormat format = ShortFormat) const;
499
500 //KDE5 make virtual?
501 /**
502 * @since 4.5
503 *
504 * Returns the Year In Era portion of a given date in the current calendar
505 * system, for example 1 for "1 BC".
506 *
507 * @param date date to return Year In Era for
508 * @return Year In Era, -1 if input date is invalid
509 */
510 int yearInEra(const QDate &date) const;
511
512 /**
513 * Returns a QDate containing a date @p nyears years later.
514 *
515 * @param date The old date
516 * @param nyears The number of years to add
517 * @return The new date, null date if any errors
518 */
519 virtual QDate addYears(const QDate &date, int nyears) const;
520
521 /**
522 * Returns a QDate containing a date @p nmonths months later.
523 *
524 * @param date The old date
525 * @param nmonths number of months to add
526 * @return The new date, null date if any errors
527 */
528 virtual QDate addMonths(const QDate &date, int nmonths) const;
529
530 /**
531 * Returns a QDate containing a date @p ndays days later.
532 *
533 * @param date The old date
534 * @param ndays number of days to add
535 * @return The new date, null date if any errors
536 */
537 virtual QDate addDays(const QDate &date, int ndays) const;
538
539 //KDE5 make virtual?
540 /**
541 * Returns the difference between two dates in years, months and days.
542 * The difference is always caculated from the earlier date to the later
543 * date in year, month and day order, with the @p direction parameter
544 * indicating which direction the difference is applied from the @p toDate.
545 *
546 * For example, the difference between 2010-06-10 and 2012-09-5 is 2 years,
547 * 2 months and 26 days. Note that the difference between two last days of
548 * the month is always 1 month, e.g. 2010-01-31 to 2010-02-28 is 1 month
549 * not 28 days.
550 *
551 * @param fromDate The date to start from
552 * @param toDate The date to end at
553 * @param yearsDiff Returns number of years difference
554 * @param monthsDiff Returns number of months difference
555 * @param daysDiff Returns number of days difference
556 * @param direction Returns direction of difference, 1 if fromDate <= toDate, -1 otherwise
557 */
558 void dateDifference(const QDate &fromDate, const QDate &toDate,
559 int *yearsDiff, int *monthsDiff, int *daysDiff, int *direction) const;
560
561 //KDE5 make virtual?
562 /**
563 * Returns the difference between two dates in completed calendar years.
564 * The returned value will be negative if @p fromDate > @p toDate.
565 *
566 * For example, the difference between 2010-06-10 and 2012-09-5 is 2 years.
567 *
568 * @param fromDate The date to start from
569 * @param toDate The date to end at
570 * @return The number of years difference
571 */
572 int yearsDifference(const QDate &fromDate, const QDate &toDate) const;
573
574 //KDE5 make virtual?
575 /**
576 * Returns the difference between two dates in completed calendar months
577 * The returned value will be negative if @p fromDate > @p toDate.
578 *
579 * For example, the difference between 2010-06-10 and 2012-09-5 is 26 months.
580 * Note that the difference between two last days of the month is always 1
581 * month, e.g. 2010-01-31 to 2010-02-28 is 1 month not 28 days.
582 *
583 * @param fromDate The date to start from
584 * @param toDate The date to end at
585 * @return The number of months difference
586 */
587 int monthsDifference(const QDate &fromDate, const QDate &toDate) const;
588
589 //KDE5 make virtual?
590 /**
591 * Returns the difference between two dates in days
592 * The returned value will be negative if @p fromDate > @p toDate.
593 *
594 * @param fromDate The date to start from
595 * @param toDate The date to end at
596 * @return The number of days difference
597 */
598 int daysDifference(const QDate &fromDate, const QDate &toDate) const;
599
600 /**
601 * Returns number of months in the given year
602 *
603 * @param date the date to obtain year from
604 * @return number of months in the year, -1 if input date invalid
605 */
606 virtual int monthsInYear(const QDate &date) const;
607
608 //KDE5 make virtual?
609 /**
610 * @since 4.5
611 *
612 * Returns number of months in the given year
613 *
614 * @param year the required year
615 * @return number of months in the year, -1 if input date invalid
616 */
617 int monthsInYear(int year) const;
618
619 /**
620 * Returns the number of localized weeks in the given year.
621 *
622 * @param date the date to obtain year from
623 * @return number of weeks in the year, -1 if input date invalid
624 */
625 virtual int weeksInYear(const QDate &date) const;
626
627 //KDE5 Merge with virtual weeksInYear with default
628 /**
629 * @since 4.7
630 *
631 * Returns the number of Weeks in a year using the required Week Number System.
632 *
633 * Unless you specifically want a particular Week Number System (e.g. ISO Weeks)
634 * you should use the localized number of weeks provided by weeksInYear().
635 *
636 * @see week()
637 * @see formatDate()
638 * @param date the date to obtain year from
639 * @param weekNumberSystem the week number system to use
640 * @return number of weeks in the year, -1 if date invalid
641 */
642 int weeksInYear(const QDate &date, KLocale::WeekNumberSystem weekNumberSystem) const;
643
644 /**
645 * Returns the number of localized weeks in the given year.
646 *
647 * @param year the year
648 * @return number of weeks in the year, -1 if input date invalid
649 */
650 virtual int weeksInYear(int year) const;
651
652 //KDE5 Merge with virtual weeksInYear with default
653 /**
654 * @since 4.7
655 *
656 * Returns the number of Weeks in a year using the required Week Number System.
657 *
658 * Unless you specifically want a particular Week Number System (e.g. ISO Weeks)
659 * you should use the localized number of weeks provided by weeksInYear().
660 *
661 * @see week()
662 * @see formatDate()
663 * @param year the year
664 * @param weekNumberSystem the week number system to use
665 * @return number of weeks in the year, -1 if date invalid
666 */
667 int weeksInYear(int year, KLocale::WeekNumberSystem weekNumberSystem) const;
668
669 /**
670 * Returns the number of days in the given year.
671 *
672 * @param date the date to obtain year from
673 * @return number of days in year, -1 if input date invalid
674 */
675 virtual int daysInYear(const QDate &date) const;
676
677 //KDE5 make virtual?
678 /**
679 * @since 4.5
680 *
681 * Returns the number of days in the given year.
682 *
683 * @param year the year
684 * @return number of days in year, -1 if input date invalid
685 */
686 int daysInYear(int year) const;
687
688 /**
689 * Returns the number of days in the given month.
690 *
691 * @param date the date to obtain month from
692 * @return number of days in month, -1 if input date invalid
693 */
694 virtual int daysInMonth(const QDate &date) const;
695
696 //KDE5 make virtual?
697 /**
698 * @since 4.5
699 *
700 * Returns the number of days in the given month.
701 *
702 * @param year the year the month is in
703 * @param month the month
704 * @return number of days in month, -1 if input date invalid
705 */
706 int daysInMonth(int year, int month) const;
707
708 /**
709 * Returns the number of days in the given week.
710 *
711 * @param date the date to obtain week from
712 * @return number of days in week, -1 if input date invalid
713 */
714 virtual int daysInWeek(const QDate &date) const;
715
716 /**
717 * Returns the day number of year for the given date
718 *
719 * The days are numbered 1..daysInYear()
720 *
721 * @param date the date to obtain day from
722 * @return day of year number, -1 if input date not valid
723 */
724 virtual int dayOfYear(const QDate &date) const;
725
726 /**
727 * Returns the weekday number for the given date
728 *
729 * The weekdays are numbered 1..7 for Monday..Sunday.
730 *
731 * This value is @em not affected by the value of weekStartDay()
732 *
733 * @param date the date to obtain day from
734 * @return day of week number, -1 if input date not valid
735 */
736 virtual int dayOfWeek(const QDate &date) const;
737
738 /**
739 * @deprecated use week() instead
740 *
741 * Returns the ISO week number for the given date.
742 *
743 * ISO 8601 defines the first week of the year as the week containing the first Thursday.
744 * See http://en.wikipedia.org/wiki/ISO_8601 and http://en.wikipedia.org/wiki/ISO_week_date
745 *
746 * If the date falls in the last week of the previous year or the first week of the following
747 * year, then the yearNum returned will be set to the appropriate year.
748 *
749 * @param date the date to obtain week from
750 * @param yearNum returns the year the date belongs to
751 * @return ISO week number, -1 if input date invalid
752 */
753 KDE_DEPRECATED virtual int weekNumber(const QDate &date, int *yearNum = 0) const;
754
755 //KDE5 Make virtual?
756 /**
757 * Returns the localized Week Number for the date.
758 *
759 * This may be ISO, US, or any other supported week numbering scheme. If
760 * you specifically require the ISO Week or any other scheme, you should use
761 * the week(KLocale::WeekNumberSystem) form.
762 *
763 * If the date falls in the last week of the previous year or the first
764 * week of the following year, then the yearNum returned will be set to the
765 * appropriate year.
766 *
767 * @see weeksInYear()
768 * @see formatDate()
769 * @param date the date to obtain week from
770 * @param yearNum returns the year the date belongs to
771 * @return localized week number, -1 if input date invalid
772 */
773 int week(const QDate &date, int *yearNum = 0) const;
774
775 //KDE5 Make virtual?
776 /**
777 * Returns the Week Number for the date in the required Week Number System.
778 *
779 * Unless you want a specific Week Number System (e.g. ISO Week), you should
780 * use the localized Week Number form of week().
781 *
782 * If the date falls in the last week of the previous year or the first
783 * week of the following year, then the yearNum returned will be set to the
784 * appropriate year.
785 *
786 * Technically, the ISO Week Number only applies to the ISO/Gregorian Calendar
787 * System, but the same rules will be applied to the current Calendar System.
788 *
789 * @see weeksInYear()
790 * @see formatDate()
791 * @param date the date to obtain week from
792 * @param weekNumberSystem the Week Number System to use
793 * @param yearNum returns the year the date belongs to
794 * @return week number, -1 if input date invalid
795 */
796 int week(const QDate &date, KLocale::WeekNumberSystem weekNumberSystem, int *yearNum = 0) const;
797
798 /**
799 * Returns whether a given year is a leap year.
800 *
801 * Input year must be checked for validity in current Calendar System prior to calling, no
802 * validity checking performed in this routine, behaviour is undefined in invalid case.
803 *
804 * @param year the year to check
805 * @return @c true if the year is a leap year, @c false otherwise
806 */
807 virtual bool isLeapYear(int year) const = 0;
808
809 /**
810 * Returns whether a given date falls in a leap year.
811 *
812 * Input date must be checked for validity in current Calendar System prior to calling, no
813 * validity checking performed in this routine, behaviour is undefined in invalid case.
814 *
815 * @param date the date to check
816 * @return @c true if the date falls in a leap year, @c false otherwise
817 */
818 virtual bool isLeapYear(const QDate &date) const;
819
820 //KDE5 Make virtual?
821 /**
822 * @since 4.6
823 *
824 * Returns a QDate containing the first day of the year
825 *
826 * @param year The year to return the date for
827 * @return The first day of the year
828 */
829 QDate firstDayOfYear(int year) const;
830
831 //KDE5 Make virtual?
832 /**
833 * @since 4.6
834 *
835 * Returns a QDate containing the last day of the year
836 *
837 * @param year The year to return the date for
838 * @return The last day of the year
839 */
840 QDate lastDayOfYear(int year) const;
841
842 //KDE5 Make virtual?
843 /**
844 * @since 4.6
845 *
846 * Returns a QDate containing the first day of the year
847 *
848 * @param date The year to return the date for, defaults to today
849 * @return The first day of the year
850 */
851 QDate firstDayOfYear(const QDate &date = QDate::currentDate()) const;
852
853 //KDE5 Make virtual?
854 /**
855 * @since 4.6
856 *
857 * Returns a QDate containing the last day of the year
858 *
859 * @param date The year to return the date for, defaults to today
860 * @return The last day of the year
861 */
862 QDate lastDayOfYear(const QDate &date = QDate::currentDate()) const;
863
864 //KDE5 Make virtual?
865 /**
866 * @since 4.6
867 *
868 * Returns a QDate containing the first day of the month
869 *
870 * @param year The year to return the date for
871 * @param month The month to return the date for
872 * @return The first day of the month
873 */
874 QDate firstDayOfMonth(int year, int month) const;
875
876 //KDE5 Make virtual?
877 /**
878 * @since 4.6
879 *
880 * Returns a QDate containing the last day of the month
881 *
882 * @param year The year to return the date for
883 * @param month The month to return the date for
884 * @return The last day of the month
885 */
886 QDate lastDayOfMonth(int year, int month) const;
887
888 //KDE5 Make virtual?
889 /**
890 * @since 4.6
891 *
892 * Returns a QDate containing the first day of the month
893 *
894 * @param date The month to return the date for, defaults to today
895 * @return The first day of the month
896 */
897 QDate firstDayOfMonth(const QDate &date = QDate::currentDate()) const;
898
899 //KDE5 Make virtual?
900 /**
901 * @since 4.6
902 *
903 * Returns a QDate containing the last day of the month
904 *
905 * @param date The month to return the date for, defaults to today
906 * @return The last day of the month
907 */
908 QDate lastDayOfMonth(const QDate &date = QDate::currentDate()) const;
909
910 /**
911 * Gets specific calendar type month name for a given month number
912 * If an invalid month is specified, QString() is returned.
913 *
914 * @param month the month number
915 * @param year the year the month belongs to
916 * @param format specifies whether the short month name or long month name should be used
917 * @return name of the month, empty string if any error
918 */
919 virtual QString monthName(int month, int year, MonthNameFormat format = LongName) const = 0;
920
921 /**
922 * Gets specific calendar type month name for a given date
923 *
924 * @param date date to obtain month from
925 * @param format specifies whether the short month name or long month name should be used
926 * @return name of the month, empty string if any error
927 */
928 virtual QString monthName(const QDate &date, MonthNameFormat format = LongName) const;
929
930 /**
931 * Gets specific calendar type week day name.
932 * If an invalid week day is specified, QString() is returned.
933 *
934 * @param weekDay number of day in week (Monday = 1, ..., Sunday = 7)
935 * @param format specifies whether the short month name or long month name should be used
936 * @return day name, empty string if any error
937 */
938 virtual QString weekDayName(int weekDay, WeekDayNameFormat format = LongDayName) const = 0;
939
940 /**
941 * Gets specific calendar type week day name.
942 *
943 * @param date the date
944 * @param format specifies whether the short month name or long month name should be used
945 * @return day name, empty string if any error
946 */
947 virtual QString weekDayName(const QDate &date, WeekDayNameFormat format = LongDayName) const;
948
949 /**
950 * @deprecated use formatDate(QDate, KLocale::DateTimeComponent, KLocale::DateTimeComponentFormat)
951 *
952 * Converts a date into a year literal
953 *
954 * @param date date to convert
955 * @param format format to return, either short or long
956 * @return year literal of the date, empty string if any error
957 * @see year()
958 */
959 KDE_DEPRECATED virtual QString yearString(const QDate &date, StringFormat format = LongFormat) const;
960
961 /**
962 * @deprecated use formatDate(QDate, KLocale::DateTimeComponent, KLocale::DateTimeComponentFormat)
963 *
964 * Converts a date into a month literal
965 *
966 * @param pDate The date to convert
967 * @param format The format to return, either short or long
968 * @return The month literal of the date, empty string if any error
969 * @see month()
970 */
971 KDE_DEPRECATED virtual QString monthString(const QDate &pDate, StringFormat format = LongFormat) const;
972
973 /**
974 * @deprecated use formatDate(QDate, KLocale::DateTimeComponent, KLocale::DateTimeComponentFormat)
975 *
976 * Converts a date into a day literal
977 *
978 * @param pDate The date to convert
979 * @param format The format to return, either short or long
980 * @return The day literal of the date, empty string if any error
981 * @see day()
982 */
983 KDE_DEPRECATED virtual QString dayString(const QDate &pDate, StringFormat format = LongFormat) const;
984
985 //KDE5 make virtual?
986 /**
987 * @deprecated use formatDate(QDate, KLocale::DateTimeComponent, KLocale::DateTimeComponentFormat)
988 *
989 * @since 4.5
990 *
991 * Converts a date into a Year In Era literal
992 *
993 * @param date date to return Year In Era for
994 * @param format format to return, either short or long
995 * @return Year In Era literal of the date, empty string if any error
996 */
997 KDE_DEPRECATED QString yearInEraString(const QDate &date, StringFormat format = ShortFormat) const;
998
999 //KDE5 make virtual?
1000 /**
1001 * @deprecated use formatDate(QDate, KLocale::DateTimeComponent, KLocale::DateTimeComponentFormat)
1002 *
1003 * @since 4.4
1004 *
1005 * Converts a date into a day of year literal
1006 *
1007 * @param pDate The date to convert
1008 * @param format The format to return, either short or long
1009 * @return The day of year literal of the date, empty string if any error
1010 * @see dayOfYear()
1011 */
1012 KDE_DEPRECATED QString dayOfYearString(const QDate &pDate, StringFormat format = LongFormat) const;
1013
1014 //KDE5 make virtual?
1015 /**
1016 * @deprecated use formatDate(QDate, KLocale::DateTimeComponent, KLocale::DateTimeComponentFormat)
1017 *
1018 * @since 4.4
1019 *
1020 * Converts a date into a day of week literal
1021 *
1022 * @param pDate The date to convert
1023 * @return The day of week literal of the date, empty string if any error
1024 * @see dayOfWeek()
1025 */
1026 KDE_DEPRECATED QString dayOfWeekString(const QDate &pDate) const;
1027
1028 //KDE5 make virtual?
1029 /**
1030 * @deprecated use formatDate(QDate, KLocale::DateTimeComponent, KLocale::DateTimeComponentFormat)
1031 *
1032 * @since 4.4
1033 *
1034 * Converts a date into a week number literal
1035 *
1036 * @param pDate The date to convert
1037 * @param format The format to return, either short or long
1038 * @return The day literal of the date, empty string if any error
1039 * @see weekNumber()
1040 */
1041 KDE_DEPRECATED QString weekNumberString(const QDate &pDate, StringFormat format = LongFormat) const;
1042
1043 //KDE5 make virtual?
1044 /**
1045 * @deprecated use formatDate(QDate, KLocale::DateTimeComponent, KLocale::DateTimeComponentFormat)
1046 *
1047 * @since 4.4
1048 *
1049 * Returns the months in year for a date as a numeric string
1050 *
1051 * @param pDate The date to convert
1052 * @param format The format to return, either short or long
1053 * @return The months in year literal of the date, empty string if any error
1054 * @see monthsInYear()
1055 */
1056 KDE_DEPRECATED QString monthsInYearString(const QDate &pDate, StringFormat format = LongFormat) const;
1057
1058 //KDE5 make virtual?
1059 /**
1060 * @deprecated use formatDate(QDate, KLocale::DateTimeComponent, KLocale::DateTimeComponentFormat)
1061 *
1062 * @since 4.4
1063 *
1064 * Returns the weeks in year for a date as a numeric string
1065 *
1066 * @param pDate The date to convert
1067 * @param format The format to return, either short or long
1068 * @return The weeks in year literal of the date, empty string if any error
1069 * @see weeksInYear()
1070 */
1071 KDE_DEPRECATED QString weeksInYearString(const QDate &pDate, StringFormat format = LongFormat) const;
1072
1073 //KDE5 make virtual?
1074 /**
1075 * @deprecated use formatDate(QDate, KLocale::DateTimeComponent, KLocale::DateTimeComponentFormat)
1076 *
1077 * @since 4.4
1078 *
1079 * Returns the days in year for a date as a numeric string
1080 *
1081 * @param pDate The date to convert
1082 * @param format The format to return, either short or long
1083 * @return The days in year literal of the date, empty string if any error
1084 * @see daysInYear()
1085 */
1086 KDE_DEPRECATED QString daysInYearString(const QDate &pDate, StringFormat format = LongFormat) const;
1087
1088 //KDE5 make virtual?
1089 /**
1090 * @deprecated use formatDate(QDate, KLocale::DateTimeComponent, KLocale::DateTimeComponentFormat)
1091 *
1092 * @since 4.4
1093 *
1094 * Returns the days in month for a date as a numeric string
1095 *
1096 * @param pDate The date to convert
1097 * @param format The format to return, either short or long
1098 * @return The days in month literal of the date, empty string if any error
1099 * @see daysInMonth()
1100 */
1101 KDE_DEPRECATED QString daysInMonthString(const QDate &pDate, StringFormat format = LongFormat) const;
1102
1103 //KDE5 make virtual?
1104 /**
1105 * @deprecated use formatDate(QDate, KLocale::DateTimeComponent, KLocale::DateTimeComponentFormat)
1106 *
1107 * @since 4.4
1108 *
1109 * Returns the days in week for a date as a numeric string
1110 *
1111 * @param date The date to convert
1112 * @return The days in week literal of the date, empty string if any error
1113 * @see daysInWeek()
1114 */
1115 KDE_DEPRECATED QString daysInWeekString(const QDate &date) const;
1116
1117 //KDE5 make protected or remove?
1118 /**
1119 * @deprecated for internal use only
1120 *
1121 * Converts a year literal of a part of a string into a integer starting at the beginning of the string
1122 *
1123 * @param sNum The string to parse
1124 * @param iLength The number of QChars used, and 0 if no valid symbols was found in the string
1125 * @return An integer corresponding to the year
1126 */
1127 virtual int yearStringToInteger(const QString &sNum, int &iLength) const;
1128
1129 //KDE5 make protected or remove?
1130 /**
1131 * @deprecated for internal use only
1132 *
1133 * Converts a month literal of a part of a string into a integer starting at the beginning of the string
1134 *
1135 * @param sNum The string to parse
1136 * @param iLength The number of QChars used, and 0 if no valid symbols was found in the string
1137 * @return An integer corresponding to the month
1138 */
1139 virtual int monthStringToInteger(const QString &sNum, int &iLength) const;
1140
1141 //KDE5 make protected or remove?
1142 /**
1143 * @deprecated for internal use only
1144 *
1145 * Converts a day literal of a part of a string into a integer starting at the beginning of the string
1146 *
1147 * @param sNum The string to parse
1148 * @param iLength The number of QChars used, and 0 if no valid symbols was found in the string
1149 * @return An integer corresponding to the day
1150 */
1151 virtual int dayStringToInteger(const QString &sNum, int &iLength) const;
1152
1153 /**
1154 * Returns a string formatted to the current locale's conventions
1155 * regarding dates.
1156 *
1157 * Uses the calendar system's internal locale set when the instance was
1158 * created, which ensures that the correct calendar system and locale
1159 * settings are respected, which would not occur in some cases if using
1160 * the global locale. Defaults to global locale.
1161 *
1162 * @see KLocale::formatDate
1163 *
1164 * @param fromDate the date to be formatted
1165 * @param toFormat category of date format to use
1166 *
1167 * @return The date as a string
1168 */
1169 virtual QString formatDate(const QDate &fromDate, KLocale::DateFormat toFormat = KLocale::LongDate) const;
1170
1171 //KDE5 Make virtual
1172 /**
1173 * @since 4.4
1174 *
1175 * Returns a string formatted to the given format and localised to the
1176 * correct language and digit set using the requested format standard.
1177 *
1178 * *** WITH GREAT POWER COMES GREAT RESPONSIBILITY ***
1179 * Please use with care and only in situations where the DateFormat enum
1180 * or locale formats or individual string methods do not provide what you
1181 * need. You should almost always translate your format string as
1182 * documented. Using the standard DateFormat options instead would take
1183 * care of the translation for you.
1184 *
1185 * Warning: The %n element differs from the GNU/POSIX standard where it is
1186 * defined as a newline. KDE currently uses this for short day number. It
1187 * is recommended for compatibility purposes to use %-m instead.
1188 *
1189 * The toFormat parameter is a good candidate to be made translatable,
1190 * so that translators can adapt it to their language's convention.
1191 * There should also be a context using the "kdedt-format" keyword (for
1192 * automatic validation of translations) and stating the format's purpose:
1193 * \code
1194 * QDate reportDate;
1195 * KGlobal::locale()->calendar()->setDate(reportDate, reportYear, reportMonth, 1);
1196 * dateFormat = i18nc("(kdedt-format) Report month and year in report header", "%B %Y"));
1197 * dateString = KGlobal::locale()->calendar()->formatDate(reportDate, dateFormat);
1198 * \endcode
1199 *
1200 * The date format string can be defined using either the KDE or POSIX standards.
1201 * The KDE standard closely follows the POSIX standard but with some exceptions.
1202 * Always use the KDE standard within KDE, but where interaction is required with
1203 * external POSIX compliant systems (e.g. Gnome, glibc, etc) the POSIX standard
1204 * should be used.
1205 *
1206 * Date format strings are made up of date componants and string literals.
1207 * Date componants are prefixed by a % escape character and are made up of
1208 * optional padding and case modifier flags, an optional width value, and a
1209 * compulsary code for the actual date componant:
1210 * %[Flags][Width][Componant]
1211 * e.g. %_^5Y
1212 * No spaces are allowed.
1213 *
1214 * The Flags can modify the padding character and/or case of the Date Componant.
1215 * The Flags are optional and may be combined and/or repeated in any order,
1216 * in which case the last Padding Flag and last Case Flag will be the
1217 * ones used. The Flags must be immediately after the % and before any Width.
1218 *
1219 * The Width can modify how wide the date Componant is padded to. The Width
1220 * is an optional interger value and must be after any Flags but before the
1221 * Componant. If the Width is less than the minimum defined for a Componant
1222 * then the default minimum will be used instead.
1223 *
1224 * By default most numeric Date Componants are right-aligned with leading 0's.
1225 *
1226 * By default all string name fields are capital case and unpadded.
1227 *
1228 * The following Flags may be specified:
1229 * @li - (hyphen) no padding (e.g. 1 Jan and "%-j" = "1")
1230 * @li _ (underscore) pad with spaces (e.g. 1 Jan and "%-j" = " 1")
1231 * @li 0 (zero) pad with 0's (e.g. 1 Jan and "%0j" = "001")
1232 * @li ^ (caret) make uppercase (e.g. 1 Jan and "%^B" = "JANUARY")
1233 * @li # (hash) invert case (e.g. 1 Jan and "%#B" = "???")
1234 *
1235 * The following Date Componants can be specified:
1236 * @li %Y the year to 4 digits (e.g. "1984" for 1984, "0584" for 584, "0084" for 84)
1237 * @li %C the 'century' portion of the year to 2 digits (e.g. "19" for 1984, "05" for 584, "00" for 84)
1238 * @li %y the lower 2 digits of the year to 2 digits (e.g. "84" for 1984, "05" for 2005)
1239 * @li %EY the full local era year (e.g. "2000 AD")
1240 * @li %EC the era name short form (e.g. "AD")
1241 * @li %Ey the year in era to 1 digit (e.g. 1 or 2000)
1242 * @li %m the month number to 2 digits (January="01", December="12")
1243 * @li %n the month number to 1 digit (January="1", December="12"), see notes!
1244 * @li %d the day number of the month to 2 digits (e.g. "01" on the first of March)
1245 * @li %e the day number of the month to 1 digit (e.g. "1" on the first of March)
1246 * @li %B the month name long form (e.g. "January")
1247 * @li %b the month name short form (e.g. "Jan" for January)
1248 * @li %h the month name short form (e.g. "Jan" for January)
1249 * @li %A the weekday name long form (e.g. "Wednesday" for Wednesday)
1250 * @li %a the weekday name short form (e.g. "Wed" for Wednesday)
1251 * @li %j the day of the year number to 3 digits (e.g. "001" for 1 Jan)
1252 * @li %V the ISO week of the year number to 2 digits (e.g. "01" for ISO Week 1)
1253 * @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)
1254 * @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)
1255 * @li %u the day of the week number to 1 digit (e.g. "1" for Monday)
1256 * @li %D the US short date format (e.g. "%m/%d/%y")
1257 * @li %F the ISO short date format (e.g. "%Y-%m-%d")
1258 * @li %x the KDE locale short date format
1259 * @li %% the literal "%"
1260 * @li %t a tab character
1261 *
1262 * Everything else in the format string will be taken as literal text.
1263 *
1264 * Examples:
1265 * "%Y-%m-%d" = "2009-01-01"
1266 * "%Y-%-m-%_4d" = "2009-1- 1"
1267 *
1268 * The following format codes behave differently in the KDE and POSIX standards
1269 * @li %e in GNU/POSIX is space padded to 2 digits, in KDE is not padded
1270 * @li %n in GNU/POSIX is newline, in KDE is short month number
1271 *
1272 * The following POSIX format codes are currently not supported:
1273 * @li %U US week number
1274 * @li %w US day of week
1275 * @li %W US week number
1276 * @li %O locale's alternative numeric symbols, in KDE is not supported
1277 *
1278 * %0 is not supported as the returned result is always in the locale's chosen numeric symbol digit set.
1279 *
1280 * @see KLocale::formatDate
1281 *
1282 * @param fromDate the date to be formatted
1283 * @param toFormat the date format to use
1284 * @param formatStandard the standard the date format uses, defaults to KDE Standard
1285 *
1286 * @return The date as a string
1287 */
1288 QString formatDate(const QDate &fromDate, const QString &toFormat,
1289 KLocale::DateTimeFormatStandard formatStandard = KLocale::KdeFormat) const;
1290
1291 //KDE5 Make virtual
1292 /**
1293 * @since 4.4
1294 *
1295 * Returns a string formatted to the given format string and Digit Set.
1296 * Only use this version if you need control over the Digit Set and do
1297 * not want to use the locale Digit Set.
1298 *
1299 * @see formatDate
1300 *
1301 * @param fromDate the date to be formatted
1302 * @param toFormat the date format to use
1303 * @param digitSet the Digit Set to format the date in
1304 * @param formatStandard the standard the date format uses, defaults to KDE Standard
1305 *
1306 * @return The date as a string
1307 */
1308 QString formatDate(const QDate &fromDate, const QString &toFormat, KLocale::DigitSet digitSet,
1309 KLocale::DateTimeFormatStandard formatStandard = KLocale::KdeFormat) const;
1310
1311 //KDE5 Make virtual
1312 /**
1313 * @since 4.6
1314 *
1315 * Returns a Date Component as a localized string in the requested format.
1316 *
1317 * For example for 2010-01-01 the KLocale::Month with en_US Locale and Gregorian calendar may return:
1318 * KLocale::ShortNumber = "1"
1319 * KLocale::LongNumber = "01"
1320 * KLocale::NarrowName = "J"
1321 * KLocale::ShortName = "Jan"
1322 * KLocale::LongName = "January"
1323 *
1324 * @param date The date to format
1325 * @param component The date component to return
1326 * @param format The format to return the @p component in
1327 * @param weekNumberSystem To override the default Week Number System to use
1328 * @return The localized string form of the date component
1329 */
1330 QString formatDate(const QDate &date, KLocale::DateTimeComponent component,
1331 KLocale::DateTimeComponentFormat format = KLocale::DefaultComponentFormat,
1332 KLocale::WeekNumberSystem weekNumberSystem = KLocale::DefaultWeekNumber) const;
1333
1334 /**
1335 * Converts a localized date string to a QDate.
1336 * The bool pointed by @p ok will be @c false if the date entered was invalid.
1337 *
1338 * Uses the calendar system's internal locale set when the instance was
1339 * created, which ensures that the correct calendar system and locale
1340 * settings are respected, which would not occur in some cases if using
1341 * the global locale. Defaults to global locale.
1342 *
1343 * @see KLocale::readDate
1344 *
1345 * @param str the string to convert
1346 * @param ok if non-null, will be set to @c true if the date is valid, @c false if invalid
1347 *
1348 * @return the string converted to a QDate
1349 */
1350 virtual QDate readDate(const QString &str, bool *ok = 0) const;
1351
1352 /**
1353 * Converts a localized date string to a QDate.
1354 * This method is stricter than readDate(str,&ok): it will either accept
1355 * a date in full format or a date in short format, depending on @p flags.
1356 *
1357 * Uses the calendar system's internal locale set when the instance was
1358 * created, which ensures that the correct calendar system and locale
1359 * settings are respected, which would not occur in some cases if using
1360 * the global locale. Defaults to global locale.
1361 *
1362 * @see KLocale::readDate
1363 *
1364 * @param str the string to convert
1365 * @param flags whether the date string is to be in full format or in short format
1366 * @param ok if non-null, will be set to @c true if the date is valid, @c false if invalid
1367 *
1368 * @return the string converted to a QDate
1369 */
1370 virtual QDate readDate(const QString &str, KLocale::ReadDateFlags flags, bool *ok = 0) const;
1371
1372 /**
1373 * Converts a localized date string to a QDate, using the specified @p format.
1374 * You will usually not want to use this method. Uses teh KDE format standard.
1375 *
1376 * @param dateString the string to convert
1377 * @param dateFormat the date format to use, in KDE format standard
1378 * @param ok if non-null, will be set to @c true if the date is valid, @c false if invalid
1379 *
1380 * @return the string converted to a QDate
1381 *
1382 * @see formatDate
1383 * @see KLocale::readDate
1384 */
1385 virtual QDate readDate(const QString &dateString, const QString &dateFormat, bool *ok = 0) const;
1386
1387 //KDE5 Make virtual
1388 /**
1389 * Converts a localized date string to a QDate, using the specified @p format.
1390 * You will usually not want to use this method.
1391 *
1392 * You must supply a format and string containing at least one of the following combinations to
1393 * create a valid date:
1394 * @li a month and day of month
1395 * @li a day of year
1396 * @li a ISO week number and day of week
1397 *
1398 * If a year number is not supplied then the current year will be assumed.
1399 *
1400 * All date componants must be separated by a non-numeric character.
1401 *
1402 * The format is not applied strictly to the input string:
1403 * @li extra whitespace is ignored
1404 * @li leading 0's on numbers are ignored
1405 * @li capitalisation of literals is ignored
1406 *
1407 * The allowed format componants are almost the same as the formatDate() function.
1408 * The following date componants will be read:
1409 * @li %Y the whole year (e.g. "1984" for 1984)
1410 * @li %y the lower 2 digits of the year (e.g. "84" for 1984)
1411 * @li %EY the full local era year (e.g. "2000 AD")
1412 * @li %EC the era name short form (e.g. "AD")
1413 * @li %Ey the year in era to 1 digit (e.g. 1 or 2000)
1414 * @li %m the month number to two digits (January="01", December="12")
1415 * @li %n the month number (January="1", December="12")
1416 * @li %d the day number of the month to two digits (e.g. "01" on the first of March)
1417 * @li %e the day number of the month (e.g. "1" on the first of March)
1418 * @li %B the month name long form (e.g. "January")
1419 * @li %b the month name short form (e.g. "Jan" for January)
1420 * @li %h the month name short form (e.g. "Jan" for January)
1421 * @li %A the weekday name long form (e.g. "Wednesday" for Wednesday)
1422 * @li %a the weekday name short form (e.g. "Wed" for Wednesday)
1423 * @li %j the day of the year number to three digits (e.g. "001" for 1 Jan)
1424 * @li %V the ISO week of the year number to two digits (e.g. "01" for ISO Week 1)
1425 * @li %u the day of the week number (e.g. "1" for Monday)
1426 *
1427 * The following date componants are NOT supported:
1428 * @li %C the 'century' portion of the year (e.g. "19" for 1984, "5" for 584, "" for 84)
1429 * @li %G the year number in long form of the ISO week of the year (e.g. "2004" for 1 Jan 2005)
1430 * @li %g the year number in short form of the ISO week of the year (e.g. "04" for 1 Jan 2005)
1431 * @li %D the US short date format (e.g. "%m/%d/%y")
1432 * @li %F the ISO short date format (e.g. "%Y-%m-%d")
1433 * @li %x the KDE locale short date format
1434 * @li %% the literal "%"
1435 * @li %t a tab character
1436 *
1437 * @param dateString the string to convert
1438 * @param dateFormat the date format to use
1439 * @param ok if non-null, will be set to @c true if the date is valid, @c false if invalid
1440 * @param formatStandard the standard the date format uses
1441 *
1442 * @return the string converted to a QDate
1443 *
1444 * @see formatDate
1445 * @see KLocale::readDate
1446 */
1447 QDate readDate(const QString &dateString, const QString &dateFormat, bool *ok,
1448 KLocale::DateTimeFormatStandard formatStandard) const;
1449
1450 //KDE5 Make virtual
1451 /**
1452 * @since 4.6
1453 *
1454 * Returns the Short Year Window Start Year for the current Calendar System.
1455 *
1456 * Use this function to get the Start Year for the Short Year Window to be
1457 * applied when 2 digit years are entered for a Short Year input format,
1458 * e.g. if the Short Year Window Start Year is 1930, then the input Short
1459 * Year value of 40 is interpreted as 1940 and the input Short Year value
1460 * of 10 is interpreted as 2010.
1461 *
1462 * The Short Year Window is only ever applied when reading the Short Year
1463 * format and not the Long Year format, i.e. KLocale::ShortFormat or '%y'
1464 * only and not KLocale::LongFormat or '%Y'.
1465 *
1466 * The Start Year 0 effectively means not to use a Short Year Window
1467 *
1468 * Each Calendar System requires a different Short Year Window as they have
1469 * different epochs. The Gregorian Short Year Window usually pivots around
1470 * the year 2000, whereas the Hebrew Short Year Window usually pivots around
1471 * the year 5000.
1472 *
1473 * This value must always be used when evaluating user input Short Year
1474 * strings.
1475 *
1476 * @see KLocale::shortYearWindowStartYear
1477 * @see KLocale::applyShortYearWindow
1478 * @return the short year window start year
1479 */
1480 int shortYearWindowStartYear() const;
1481
1482 //KDE5 Make virtual
1483 /**
1484 * @since 4.6
1485 *
1486 * Returns the Year Number after applying the Year Window.
1487 *
1488 * If the @p inputYear is between 0 and 99, then apply the Year Window and
1489 * return the calculated Year Number.
1490 *
1491 * If the @p inputYear is not between 0 and 99, then the original Year Number
1492 * is returned.
1493 *
1494 * @see KLocale::setYearWindowOffset
1495 * @see KLocale::yearWindowOffset
1496 * @param inputYear the year number to apply the year window to
1497 * @return the year number after applying the year window
1498 */
1499 int applyShortYearWindow(int inputYear) const;
1500
1501 /**
1502 * Use this to determine which day is the first day of the week.
1503 *
1504 * Uses the calendar system's internal locale set when the instance was
1505 * created, which ensures that the correct calendar system and locale
1506 * settings are respected, which would not occur in some cases if using
1507 * the global locale. Defaults to global locale.
1508 *
1509 * @see KLocale::weekStartDay
1510 *
1511 * @return an integer (Monday = 1, ..., Sunday = 7)
1512 */
1513 virtual int weekStartDay() const;
1514
1515 /**
1516 * @deprecated use KLocale::weekDayOfPray() instead
1517 *
1518 * Returns the day of the week traditionally associated with religious
1519 * observance for this calendar system. Note this may not be accurate
1520 * for the users locale, e.g. Gregorian calendar used in non-Christian
1521 * countries, in use cases where this could be an issue it is recommended
1522 * to use KLocale::weekDayOfPray() instead.
1523 *
1524 * @return day number (None = 0, Monday = 1, ..., Sunday = 7)
1525 */
1526 KDE_DEPRECATED virtual int weekDayOfPray() const = 0;
1527
1528 /**
1529 * Returns whether the calendar is lunar based.
1530 *
1531 * @return @c true if the calendar is lunar based, @c false if not
1532 */
1533 virtual bool isLunar() const = 0;
1534
1535 /**
1536 * Returns whether the calendar is lunisolar based.
1537 *
1538 * @return @c true if the calendar is lunisolar based, @c false if not
1539 */
1540 virtual bool isLunisolar() const = 0;
1541
1542 /**
1543 * Returns whether the calendar is solar based.
1544 *
1545 * @return @c true if the calendar is solar based, @c false if not
1546 */
1547 virtual bool isSolar() const = 0;
1548
1549 /**
1550 * Returns whether the calendar system is proleptic, i.e. whether dates
1551 * before the epoch are supported.
1552 *
1553 * @see KCalendarSystem::epoch
1554 *
1555 * @return @c true if the calendar system is proleptic, @c false if not
1556 */
1557 virtual bool isProleptic() const = 0;
1558
1559protected:
1560
1561 /**
1562 * Internal method to convert a Julian Day number into the YMD values for
1563 * this calendar system.
1564 *
1565 * All calendar system implementations MUST implement julianDayToDate and
1566 * dateToJulianDay methods as all other methods can be expressed as
1567 * functions of these. Does no internal validity checking.
1568 *
1569 * @see KCalendarSystem::dateToJulianDay
1570 *
1571 * @param jd Julian day number to convert to date
1572 * @param year year number returned in this variable
1573 * @param month month number returned in this variable
1574 * @param day day of month returned in this variable
1575 * @return @c true if the date is valid, @c false otherwise
1576 */
1577 virtual bool julianDayToDate(int jd, int &year, int &month, int &day) const = 0;
1578
1579 /**
1580 * Internal method to convert YMD values for this calendar system into a
1581 * Julian Day number.
1582 *
1583 * All calendar system implementations MUST implement julianDayToDate and
1584 * dateToJulianDay methods as all other methods can be expressed as
1585 * functions of these. Does no internal validity checking.
1586 *
1587 * @see KCalendarSystem::julianDayToDate
1588 *
1589 * @param year year number
1590 * @param month month number
1591 * @param day day of month
1592 * @param jd Julian day number returned in this variable
1593 * @return @c true if the date is valid, @c false otherwise
1594 */
1595 virtual bool dateToJulianDay(int year, int month, int day, int &jd) const = 0;
1596
1597 /**
1598 * Returns the locale used for translations and formats for this
1599 * calendar system instance. This allows a calendar system instance to be
1600 * independent of the global translations and formats if required. All
1601 * implementations must refer to this locale.
1602 *
1603 * Only for internal calendar system use; if public access is required then
1604 * provide public methods only for those methods actually required. Any
1605 * app that creates an instance with its own locale overriding global will
1606 * have the original handle to the locale and can manipulate it that way if
1607 * required, e.g. to change default date format. Only expose those methods
1608 * that library widgets require access to internally.
1609 *
1610 * @see KCalendarSystem::formatDate
1611 * @see KLocale::formatDate
1612 * @see KCalendarSystem::weekStartDay
1613 * @see KLocale::weekStartDay
1614 * @see KCalendarSystem::readDate
1615 * @see KLocale::readDate
1616 *
1617 * @return locale to use
1618 */
1619 const KLocale *locale() const;
1620
1621 /**
1622 * @deprecated for internal use only
1623 *
1624 * Sets the maximum number of months in a year
1625 *
1626 * Only for internal calendar system use
1627 */
1628 KDE_DEPRECATED void setMaxMonthsInYear(int maxMonths);
1629
1630 /**
1631 * @deprecated for internal use only
1632 *
1633 * Sets the maximum number of days in a week
1634 *
1635 * Only for internal calendar system use
1636 */
1637 KDE_DEPRECATED void setMaxDaysInWeek(int maxDays);
1638
1639 /**
1640 * @deprecated for internal use only
1641 *
1642 * @since 4.4
1643 *
1644 * Sets if Calendar System has Year 0 or not
1645 *
1646 * Only for internal calendar system use
1647 */
1648 KDE_DEPRECATED void setHasYear0(bool hasYear0);
1649
1650 /**
1651 * Constructor of abstract calendar class. This will be called by derived classes.
1652 *
1653 * @param dd derived private d-pointer.
1654 * @param config a configuration file with a 'KCalendarSystem %calendarName' group detailing
1655 * locale-related preferences (such as era options). The global config is used
1656 if null.
1657 * @param locale locale to use for translations. The global locale is used if null.
1658 */
1659 KCalendarSystem(KCalendarSystemPrivate &dd,
1660 const KSharedConfig::Ptr config = KSharedConfig::Ptr(),
1661 const KLocale *locale = 0);
1662
1663private:
1664 //Required for shared d-pointer as already private, remove in KDE5
1665 friend class KCalendarSystemCoptic;
1666 friend class KCalendarSystemEthiopian;
1667 friend class KCalendarSystemGregorian;
1668 friend class KCalendarSystemHebrew;
1669 friend class KCalendarSystemIndianNational;
1670 friend class KCalendarSystemIslamicCivil;
1671 friend class KCalendarSystemJalali;
1672 friend class KCalendarSystemJapanese;
1673 friend class KCalendarSystemJulian;
1674 friend class KCalendarSystemMinguo;
1675 friend class KCalendarSystemQDate;
1676 friend class KCalendarSystemThai;
1677 //Other friends that need access to protected/private functions
1678 friend class KLocalizedDate;
1679 friend class KLocalizedDatePrivate;
1680 friend class KDateTimeParser;
1681 friend class KDateTable;
1682
1683 // Era functions needed by friends, may be made public later if needed in KCM
1684 QList<KCalendarEra> *eraList() const;
1685 KCalendarEra era(const QDate &eraDate) const;
1686 KCalendarEra era(const QString &eraName, int yearInEra) const;
1687
1688 Q_DISABLE_COPY(KCalendarSystem)
1689 KCalendarSystemPrivate * const d_ptr; // KDE5 make protected
1690 Q_DECLARE_PRIVATE(KCalendarSystem)
1691};
1692
1693#endif
1694

Warning: That file was not part of the compilation database. It may have many parsing errors.