KDELibs4Support

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

KDE's Doxygen guidelines are available online.