KDELibs4Support

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

KDE's Doxygen guidelines are available online.