2
Copyright 2010 John Layt <john@layt.net>
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.
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.
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.
23
#include <QtCore/QString>
24
#include <QtCore/QDate>
26
#include <kdecore_export.h>
27
#include "kcalendarsystem.h"
30
class KLocalizedDatePrivate;
32
* @short A class representing a date localized using the local calendar system, language and formats
41
* @section intro Introduction
43
* This class provides a simple and convenient way to localize dates
45
* @section calsys Calendar System
47
* KDE supports the use of different calendar systems.
49
* @section custom Default and Custom Locale and Calendar System
51
* In most cases you will want to use the default Global Locale and Calendar
52
* System, in which case you need only create a default KLocalizedDate. If
53
* however you specifically need a different Calendar System or Locale settings
54
* then you need to take some extra steps.
56
* The simplest method is just changing the Calendar System while keeping the
57
* current Locale settings. This is easily done using setCalendarSystem()
58
* which will copy the current Locale being used and apply this to the new
59
* Calendar System. Note this means any changes to the old locale settings,
60
* either the Global Locale or a custom Locale (see below) will not apply
61
* to that date instance.
63
* You may however wish to use a custom Locale with the Calendar System.
64
* For example, if you want your app to normally show dates using the Global
65
* Locale and Calendar System, but wish to show an info box with the Islamic
66
* date in Arabic language and format, then you need a custom Locale to do
70
* KLocale *myLocale = new KLocale("myapp", "ar", "eg");
71
* KCalendarSystem *myCalendar = KCalendarSystem::create(KLocale::IslamicCivilCalendar, myLocale);
72
* KLocalizedDate myDate(QDate(2010,1,1), myCalendar);
75
* In this case you are responsible for the memory management of the KLocale
76
* and KCalendarSystem. This allows you to reuse this calendar across multiple
77
* date instances without it being deleted under you. It also allows you to
78
* change any setting in the Locale and have it apply acrooss all those date
79
* instances. @warning Don't try changing the Calendar System via your Locale
80
* instance, your KCalendarSystem instance will be deleted and all the dates
85
* @section formatting Date Formatting
87
* When you display dates or date components to users in a GUI, they will
88
* expect them to be displayed in their language and digit set following their
89
* local date formatting conventions. Directly displaying values returned by
90
* the normal date component methods such as day() will not conform to these
91
* expectations, so you need to use different methods to obtain the localized
92
* string form of the date or component.
94
* You can either format the entire date, or just a single component of the
95
* date such as the month or day.
97
* When formatting a full date, it is preferred to use one of the standard date
98
* formats defined in the Locale, although you can provide your own format in
99
* either the KDE, POSIX, or UNICODE standards.
101
* @see formatDate() formatDateComponent() formatWeek() formatDayOfWeek()
103
* @section parsing Date Parsing
105
* Basic concepts on date parsing, then full details on KLocale::ReadDateFlags
106
* formats, definging your own date format strings, and setting how strictly
107
* the format is appplied.
109
* You can choose how strictly a date format is applied in parsing. Currently
110
* only liberal Parsing is supported.
112
* The KLocale::LiberalParsing mode applies the following rules:
114
* 1) You must supply a format and string containing at least one of the following combinations to
115
* create a valid date:
116
* @li a month and day of month
118
* @li a ISO week number and day of week
120
* 2) If a year number is not supplied then the current year will be assumed.
122
* 3) All date componants must be separated by a non-numeric character.
124
* 4) The format is not applied strictly to the input string:
125
* @li extra whitespace is ignored
126
* @li leading 0's on numbers are ignored
127
* @li capitalisation of literals is ignored
131
* @section maths Date Maths
133
* A full set of date maths functions are provided which operate in a consistent
134
* manner, i.e. you can safely round-trip.
138
class KDECORE_EXPORT KLocalizedDate
143
* Constructs a localized date with the given date.
145
* By default, uses the global Calendar System and Locale.
147
* If you pass in a custom Calendar System then you retain ownership of it
148
* and are responsible for deleting it. This allows you to reuse the same
149
* custom Calendar System for many localized date instances.
151
* See @ref custom for more details on using custom Calendar Systems.
153
* @param date the QDate to set the KLocalizedDate to, defaults to invalid date
154
* @param locale the locale to use for date formats, defaults to the global
156
explicit KLocalizedDate(const QDate &date = QDate(), const KCalendarSystem *calendar = 0);
159
* Constructs a localized date with the given year, month and day.
161
* By default, uses the global Calendar System and Locale.
163
* If you pass in a custom Calendar System then you retain ownership of it
164
* and are responsible for deleting it. This allows you to reuse the same
165
* custom Calendar System for many localized date instances.
167
* See @ref custom for more details on using custom Calendar Systems.
169
* @param year the year to set the KLocalizedDate to
170
* @param month the month to set the KLocalizedDate to
171
* @param day the day to set the KLocalizedDate to
173
KLocalizedDate(int year, int month, int day, const KCalendarSystem *calendar = 0);
178
* @param rhs the date to copy
180
KLocalizedDate(const KLocalizedDate &rhs);
183
* Assignment operator
185
* @param rhs the date to assign
187
KLocalizedDate &operator=(const KLocalizedDate &rhs);
190
* Assignment operator
192
* @param rhs the date to assign
194
KLocalizedDate &operator=(const QDate &rhs);
202
* Set the Calendar System used for this date instance only.
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.
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.
213
* See @ref custom for more details on using custom Calendar Systems.
215
* @see KLocale::CalendarSystem
216
* @see calendarSystem()
217
* @param calendarSystem the Calendar System to use
219
void setCalendarSystem(KLocale::CalendarSystem calendarSystem);
222
* Returns the Calendar System used by this localized date instance
224
* @see KLocale::CalendarSystem
225
* @see setCalendarSystem()
226
* @return the Calendar System currently used
228
KLocale::CalendarSystem calendarSystem();
231
* Returns a pointer to the Calendar System object used by this date instance.
233
* Usually this will be the Global Calendar System, but this may have been
236
* Normally you will not need to access this object unless the KLocalizedDate
237
* API does not provide the methods you require.
239
* @see KCalendarSystem
240
* @see calendarSystem
241
* @see setCalendarSystem
242
* @return the current calendar system instance
244
const KCalendarSystem *calendar() const;
247
* Returns whether the date is null, i.e. invalid in any Calendar System.
250
* @return @c true if the date is null, @c false otherwise
255
* Returns whether the date is valid in the current Calendar System.
258
* @return @c true if the date is valid, @c false otherwise
260
bool isValid() const;
263
* Set the date using a QDate.
265
* @param date the QDate to set to
266
* @return @c true if the date is valid, @c false otherwise
268
bool setDate(const QDate &date);
271
* Set the date's year, month and day.
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.
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
282
bool setDate(int year, int month, int day);
285
* Set the date using the year number and day of year number only.
289
* @param dayOfYear day of year
290
* @return @c true if the date is valid, @c false otherwise
292
bool setDate(int year, int dayOfYear);
295
* Set the date using the era, year in era number, month and day
299
* @param eraName Era string
300
* @param year 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
305
bool setDate(QString eraName, int yearInEra, int month, int day);
308
* Set the date using the year, week and day of week.
310
* Currently only the ISO Week Number System is supported.
314
* @param weekNumberSystem the week number system to use
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
320
bool setDate(KLocale::WeekNumberSystem weekNumberSystem, int year, int weekOfYear, int dayOfWeek);
323
* Set the date to today's date
326
* @return @c true if the date is valid, @c false otherwise
328
bool setCurrentDate();
331
* Returns a KLocalizedDate set to today's date in the Global Locale and
334
* @see setCurrentDate()
335
* @return today's localized date
337
static KLocalizedDate currentDate();
340
* Returns a KLocalizedDate set the required date in the Global Locale and
343
* @param date the date to set to
344
* @return a localized date
346
static KLocalizedDate fromDate(const QDate &date);
349
* Returns a KLocalizedDate set the required Julian Day number in the Global
350
* Locale and Calendar System.
353
* @param jd the Julian Day number to set to
354
* @return a localized date
356
static KLocalizedDate fromJulianDay(int jd);
359
* Returns the currently set date as a Julian Day number
361
* @see fromJulianDay()
362
* @return the currently set date as a Julian Day number
364
int toJulianDay() const;
367
* Returns the currently set date as a QDate
369
* @return the currently set date as a QDate
374
* Returns the year, month and day portion of the date in the current
377
* See @ref formatting for why you should never display this value.
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
385
void getDate(int *year, int *month, int *day) const;
388
* Returns the year portion of the date in the current calendar system
390
* See @ref formatting for why you should never display this value.
392
* @see formatDateComponent()
393
* @return the localized year number
398
* Returns the month portion of the date in the current calendar system
400
* See @ref formatting for why you should never display this value.
402
* @see formatDateComponent()
403
* @return the localized month number, 0 if date is invalid
408
* Returns the day portion of the date in the current calendar system
410
* See @ref formatting for why you should never display this value.
412
* @see formatDateComponent()
413
* @return the localized day number, 0 if date is invalid
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.
421
* See @ref formatting for more details on Date Formatting.
423
* @see formatDateComponent()
424
* @param format format to return, either short or long
425
* @return the localized era name, empty string if date is invalid
427
QString eraName() const;
430
* Returns the Era Year portion of the date in the current
431
* calendar system, for example "2000 AD" or "Heisei 22".
433
* See @ref formatting for more details on Date Formatting.
435
* @see formatDateComponent()
436
* @param format format to return, either short or long
437
* @return the localized era year string, empty string if date is invalid
439
QString eraYear() const;
442
* Returns the Year In Era portion of the date in the current calendar
443
* system, for example 1 for "1 BC".
445
* See @ref formatting for why you should never display this value.
447
* @see formatDateComponent()
448
* @see formatYearInEra()
449
* @return the localized Year In Era number, -1 if date is invalid
451
int yearInEra() const;
454
* Returns the day number of year for the date
456
* See @ref formatting for why you should never display this value.
458
* @see formatDateComponent()
459
* @return day of year number, -1 if date not valid
461
int dayOfYear() const;
464
* Returns the weekday number for the date
466
* See @ref formatting for why you should never display this value.
468
* @see formatDateComponent()
469
* @return day of week number, -1 if date not valid
471
int dayOfWeek() const;
474
* Returns the localized Week Number for the date.
476
* See @ref formatting for why you should never display this value.
478
* Currently only the ISO Week Number is supported, but in future the US
479
* and other week number systems will be added.
481
* If you specifically require the ISO Week, you should use
482
* week(KLocale::IsoWeekNumber)
484
* ISO 8601 defines the first week of the year as the week containing the first Thursday.
485
* See http://en.wikipedia.org/wiki/ISO_8601 and http://en.wikipedia.org/wiki/ISO_week_date
487
* If the date falls in the last week of the previous year or the first
488
* week of the following year, then the yearNum returned will be set to the
492
* @see formatDateComponent()
493
* @param yearNum returns the year the date belongs to
494
* @return localized week number, -1 if input date invalid
496
int week(int *yearNum = 0) const;
499
* Returns the Week Number for the date in the required Week Number System.
501
* See @ref formatting for why you should never display this value.
503
* Unless you want a specific Week Number System (e.g. ISO Week), you should
504
* use the localized Week Number form of week().
506
* If the date falls in the last week of the previous year or the first
507
* week of the following year, then the yearNum returned will be set to the
510
* Technically, the ISO Week Number only applies to the ISO/Gregorian Calendar
511
* System, but the same rules will be applied to the current Calendar System.
514
* @see formatDateComponent()
515
* @param weekNumberSystem the Week Number System to use
516
* @param yearNum returns the year the date belongs to
517
* @return week number, -1 if input date invalid
519
int week(KLocale::WeekNumberSystem weekNumberSystem, int *yearNum = 0) const;
522
* Returns number of months in the year
524
* See @ref formatting for why you should never display this value.
526
* @see formatDateComponent()
527
* @return number of months in the year, -1 if date invalid
529
int monthsInYear() const;
532
* Returns the number of localized weeks in the currently set year.
534
* See @ref formatting for why you should never display this value.
536
* Currently only the ISO Week Number is supported, but in future the US
537
* and other week number systems will be added.
539
* If you specifically require the number of ISO Weeks, you should use
540
* weeksInYear(KLocale::IsoWeekNumber)
543
* @see formatDateComponent()
544
* @return number of weeks in the year, -1 if date invalid
546
int weeksInYear() const;
549
* Returns the number of Weeks in the currently set year using the required
550
* Week Number System.
552
* See @ref formatting for why you should never display this value.
554
* Unless you specifically want a particular Week Number System (e.g. ISO Weeks)
555
* you should use the localized number of weeks provided by weeksInYear().
558
* @see formatDateComponent()
559
* @param weekNumberSystem the week number system to use
560
* @return number of weeks in the year, -1 if date invalid
562
int weeksInYear(KLocale::WeekNumberSystem weekNumberSystem) const;
565
* Returns the number of days in the year.
567
* For example, in the Gregorian calendar most years have 365 days but Leap
568
* Years have 366 years. Other Calendar Systems have different length years.
570
* See @ref formatting for why you should never display this value.
572
* @see formatDateComponent()
573
* @return number of days in year, -1 if date invalid
575
int daysInYear() const;
578
* Returns the number of days in the month.
580
* See @ref formatting for why you should never display this value.
582
* @see formatDateComponent()
583
* @return number of days in month, -1 if date invalid
585
int daysInMonth() const;
588
* Returns the number of days in the week.
590
* See @ref formatting for why you should never display this value.
592
* @see formatDateComponent()
593
* @return number of days in week, -1 if date invalid
595
int daysInWeek() const;
598
* Returns whether the currently set date falls in a Leap Year in the
599
* current Calendar System.
601
* @return true if the date falls in a leap year
603
bool isLeapYear() const;
606
* Returns the Date as a localized string in the requested standard Locale
609
* See @ref formatting for more details on Date Formatting and valid Locale
612
* @see formatDateComponent()
613
* @param dateFormat the standard date format to use
614
* @return The date as a localized string
616
QString formatDate(KLocale::DateFormat dateFormat = KLocale::LongDate) const;
619
* Returns the Date as a localized string in the requested format.
621
* See @ref formatting for more details on Date Formatting and valid format
624
* Please use with care and only in situations where the standard Locale
625
* formats or the componant format methods do not provide what you
626
* need. You should almost always translate your @p formatString as
627
* documented above. Using the standard DateFormat options instead would
628
* take care of the translation for you.
630
* The toFormat parameter is a good candidate to be made translatable,
631
* so that translators can adapt it to their language's convention.
632
* There should also be a context using the "kdedt-format" keyword (for
633
* automatic validation of translations) and stating the format's purpose:
636
* KGlobal::locale()->calendar()->setDate(reportDate, reportYear, reportMonth, 1);
637
* dateFormat = i18nc("(kdedt-format) Report month and year in report header", "%B %Y"));
638
* dateString = KGlobal::locale()->calendar()->formatDate(reportDate, dateFormat);
641
* The date format string can be defined using either the KDE, POSIX or the Qt
642
* subset of the UNICODE standards.
644
* The KDE standard closely follows the POSIX standard but with some exceptions.
645
* Always use the KDE standard within KDE, but where interaction is required with
646
* external POSIX compliant systems (e.g. Gnome, glibc, etc) the POSIX standard
647
* should be used. The UNICODE standard is provided for comaptability with QDate
648
* and so is not yet the full standard, only what Qt currently supports.
650
* Date format strings are made up of date componants and string literals.
651
* Date componants are prefixed by a % escape character and are made up of
652
* optional padding and case modifier flags, an optional width value, and a
653
* compulsary code for the actual date componant:
654
* %[Flags][Width][Componant]
656
* No spaces are allowed.
658
* The Flags can modify the padding character and/or case of the Date Componant.
659
* The Flags are optional and may be combined and/or repeated in any order,
660
* in which case the last Padding Flag and last Case Flag will be the
661
* ones used. The Flags must be immediately after the % and before any Width.
663
* The Width can modify how wide the date Componant is padded to. The Width
664
* is an optional interger value and must be after any Flags but before the
665
* Componant. If the Width is less than the minimum defined for a Componant
666
* then the default minimum will be used instead.
668
* By default most numeric Date Componants are right-aligned with leading 0's.
670
* By default all string name fields are capital case and unpadded.
672
* The following Flags may be specified:
673
* @li - (hyphen) no padding (e.g. 1 Jan and "%-j" = "1")
674
* @li _ (underscore) pad with spaces (e.g. 1 Jan and "%-j" = " 1")
675
* @li 0 (zero) pad with 0's (e.g. 1 Jan and "%0j" = "001")
676
* @li ^ (caret) make uppercase (e.g. 1 Jan and "%^B" = "JANUARY")
677
* @li # (hash) invert case (e.g. 1 Jan and "%#B" = "???")
679
* The following Date Componants can be specified:
680
* @li %Y the year to 4 digits (e.g. "1984" for 1984, "0584" for 584, "0084" for 84)
681
* @li %C the 'century' portion of the year to 2 digits (e.g. "19" for 1984, "05" for 584, "00" for 84)
682
* @li %y the lower 2 digits of the year to 2 digits (e.g. "84" for 1984, "05" for 2005)
683
* @li %EY the full local era year (e.g. "2000 AD")
684
* @li %EC the era name short form (e.g. "AD")
685
* @li %Ey the year in era to 1 digit (e.g. 1 or 2000)
686
* @li %m the month number to 2 digits (January="01", December="12")
687
* @li %n the month number to 1 digit (January="1", December="12"), see notes!
688
* @li %d the day number of the month to 2 digits (e.g. "01" on the first of March)
689
* @li %e the day number of the month to 1 digit (e.g. "1" on the first of March)
690
* @li %B the month name long form (e.g. "January")
691
* @li %b the month name short form (e.g. "Jan" for January)
692
* @li %h the month name short form (e.g. "Jan" for January)
693
* @li %A the weekday name long form (e.g. "Wednesday" for Wednesday)
694
* @li %a the weekday name short form (e.g. "Wed" for Wednesday)
695
* @li %j the day of the year number to 3 digits (e.g. "001" for 1 Jan)
696
* @li %V the ISO week of the year number to 2 digits (e.g. "01" for ISO Week 1)
697
* @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)
698
* @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)
699
* @li %u the day of the week number to 1 digit (e.g. "1" for Monday)
700
* @li %D the US short date format (e.g. "%m/%d/%y")
701
* @li %F the ISO short date format (e.g. "%Y-%m-%d")
702
* @li %x the KDE locale short date format
703
* @li %% the literal "%"
704
* @li %t a tab character
706
* Everything else in the format string will be taken as literal text.
709
* "%Y-%m-%d" = "2009-01-01"
710
* "%Y-%-m-%_4d" = "2009-1- 1"
712
* The following format codes behave differently in the KDE and POSIX standards
713
* @li %e in GNU/POSIX is space padded to 2 digits, in KDE is not padded
714
* @li %n in GNU/POSIX is newline, in KDE is short month number
716
* The following POSIX format codes are currently not supported:
717
* @li %U US week number
718
* @li %w US day of week
719
* @li %W US week number
720
* @li %O locale's alternative numeric symbols, in KDE is not supported
722
* %0 is not supported as the returned result is always in the locale's chosen numeric symbol digit set.
724
* @see formatDateComponent()
725
* @param formatString the date format to use
726
* @param formatStandard the standard the @p dateFormat uses, defaults to KDE Standard
727
* @return The date as a localized string
729
QString formatDate(const QString &formatString,
730
KLocale::DateTimeFormatStandard formatStandard = KLocale::KdeFormat) const;
733
* Returns a Date Component as a localized string in the requested format.
735
* See @ref formatting for more details on Date Formatting.
737
* Each format size may vary depending on Locale and Calendar System but will
738
* generally match the format description. Some formats may not be directly
739
* valid but a sensible value will always be returned.
741
* For example for 2010-01-01 the KLocale::Month with en_US Locale and Gregorian calendar may return:
742
* KLocale::ShortNumber = "1"
743
* KLocale::LongNumber = "01"
744
* KLocale::NarrowName = "J"
745
* KLocale::ShortName = "Jan"
746
* KLocale::LongName = "January"
749
* @param component The date component to return
750
* @param format The format to return the @p component in
751
* @return The string form of the date component
753
QString formatDateComponent(KLocale::DateTimeComponent component, KLocale::DateTimeComponentFormat format = KLocale::DefaultComponentFormat) const;
756
* Returns the Week as a localized string in the requested format
757
* and Week Number System.
759
* See @ref formatting for more details on Date Formatting.
761
* For example for Week 1 with en_US Locale and Gregorian calendar may return:
762
* KLocale::ShortNumber = "1"
763
* KLocale::LongNumber = "01"
765
* This is the equivalent of the POSIX date format code "%" and "%"
768
* @see formatWeeksInYear()
769
* @see formatDateComponent()
770
* @param weekNumberSystem the Week Number System to use
771
* @param format The format to return
772
* @return The string form of the week number
774
QString formatWeek(KLocale::WeekNumberSystem weekNumberSystem, KLocale::DateTimeComponentFormat format = KLocale::DefaultComponentFormat) const;
777
* Returns the Weeks In Year as a localized string in the requested format
778
* and Week Number System.
780
* See @ref formatting for more details on Date Formatting.
782
* For example for Week 1 with en_US Locale and Gregorian calendar may return:
783
* KLocale::ShortNumber = "1"
784
* KLocale::LongNumber = "01"
786
* This is the equivalent of the POSIX date format code "%" and "%"
791
* @see formatDateComponent()
792
* @param format The format to return
793
* @return The string form of the weeks in year
795
QString formatWeeksInYear(KLocale::WeekNumberSystem weekNumberSystem, KLocale::DateTimeComponentFormat format = KLocale::DefaultComponentFormat) const;
798
* Converts a localized date string to a KLocalizedDate using either the
799
* Global Calendar System and Locale, or the provided Calendar System.
801
* See @ref parsing for more details on Date Parsing from strings.
803
* This method is more liberal and will return a valid date if the
804
* @p dateString matches any of the KLocale::ReadDateFlags formats
807
* If you require a certain KLocale::ReadDateFlags format or a customized
808
* format string, use one of the other readDate() methods.
810
* @param dateString the string to parse
811
* @param parseMode how strictly to apply the locale formats to the @p dateString
812
* @param calendar the Calendar System to use when parsing the date
813
* @return the localized date parsed from the string
815
static KLocalizedDate readDate(const QString &dateString,
816
KLocale::DateTimeParseMode parseMode = KLocale::LiberalParsing,
817
const KCalendarSystem *calendar = 0);
820
* Converts a localized date string to a KLocalizedDate using either the
821
* Global Calendar System and Locale, or the provided Calendar System.
823
* See @ref parsing for more details on Date Parsing from strings.
825
* This method is stricter and will return a valid date only if the
826
* @p dateString matches one of the @p dateFlags formats requested.
828
* If you require any KLocale::ReadDateFlags format or a customized format
829
* string, use one of the other readDate() methods.
831
* @param dateString the string to parse
832
* @param formatFlags the locale format(s) to try parse the string with
833
* @param parseMode how strictly to apply the @p formatFlags to the @p dateString
834
* @param calendar the Calendar System to use when parsing the date
835
* @return the localized date parsed from the string
837
static KLocalizedDate readDate(const QString &dateString,
838
KLocale::ReadDateFlags formatFlags,
839
KLocale::DateTimeParseMode parseMode = KLocale::LiberalParsing,
840
const KCalendarSystem *calendar = 0);
843
* Converts a localized date string to a KLocalizedDate using either the
844
* Global Calendar System and Locale, or the provided Calendar System.
846
* See @ref parsing for more details on Date Parsing from strings.
848
* This method allows you to define your own date format to parse the date
851
* If you require one of the standard any KLocale::ReadDateFlags formats
852
* then use one of the other readDate() methods.
854
* @param dateString the string to parse
855
* @param dateFormat the date format to try parse the string with
856
* @param parseMode how strictly to apply the @p dateFormat to the @p dateString
857
* @param formatStandard the standard the @p dateFormat format uses
858
* @param calendar the Calendar System to use when parsing the date
859
* @return the localized date parsed from the string
861
static KLocalizedDate readDate(const QString &dateString,
862
const QString &dateFormat,
863
KLocale::DateTimeParseMode parseMode = KLocale::LiberalParsing,
864
KLocale::DateTimeFormatStandard formatStandard = KLocale::KdeFormat,
865
const KCalendarSystem *calendar = 0);
868
* Returns a KLocalizedDate containing a date @p years years later.
871
* @see addMonths() addDays()
872
* @see dateDifference() yearsDifference()
873
* @param years The number of years to add
874
* @return The new date, null date if any errors
876
KLocalizedDate addYears(int years) const;
879
* Add years onto this date instance.
881
* If the result of the addition is invalid in the current Calendar System
882
* then the date will become invalid.
885
* @see addMonthsTo() addDaysTo()
886
* @see dateDifference() yearsDifference()
887
* @param years The number of years to add
888
* @return if the resulting date is valid
890
bool addYearsTo(int years);
893
* Returns a KLocalizedDate containing a date @p months months later.
896
* @see addYears() addDays()
897
* @see dateDifference() yearsDifference()
898
* @param months number of months to add
899
* @return The new date, null date if any errors
901
KLocalizedDate addMonths(int months) const;
904
* Add months onto this date instance.
906
* If the result of the addition is invalid in the current Calendar System
907
* then the date will become invalid.
910
* @see addYearsTo() addDaysTo()
911
* @see dateDifference() yearsDifference()
912
* @param months The number of months to add
913
* @return if the resulting date is valid
915
bool addMonthsTo(int months);
918
* Returns a KLocalizedDate containing a date @p days days later.
921
* @see addYears() addMonths()
922
* @see dateDifference() yearsDifference()
923
* @param days number of days to add
924
* @return The new date, null date if any errors
926
KLocalizedDate addDays(int days) const;
929
* Add days onto this date instance.
931
* If the result of the addition is invalid in the current Calendar System
932
* then the date will become invalid.
935
* @see addYearsTo(), addMonthsTo()
936
* @see dateDifference() yearsDifference()
937
* @param days The number of days to add
938
* @return if the resulting date is valid
940
bool addDaysTo(int days);
943
* Returns the difference between this and another date in years, months and days
944
* in the current Calendar System.
946
* The difference is always calculated from the earlier date to the later
947
* date in year, month and day order, with the @p direction parameter
948
* indicating which direction the difference is applied from this date.
949
* In other words, this difference can be added onto the earlier date in
950
* year, month, day order to reach the later date.
952
* For example, the difference between 2010-06-10 and 2012-09-5 is 2 years,
953
* 2 months and 26 days. Note that the difference between two last days of
954
* the month is always 1 month, e.g. 2010-01-31 to 2010-02-28 is 1 month
957
* @see addYears() addMonths() addDays()
958
* @see yearsDifference() monthsDifference() daysDifference()
959
* @param toDate The date to end at
960
* @param yearsDiff Returns number of years difference
961
* @param monthsDiff Returns number of months difference
962
* @param daysDiff Returns number of days difference
963
* @param direction Returns direction of difference, 1 if this Date <= toDate, -1 otherwise
965
void dateDifference(const KLocalizedDate &toDate,
966
int *yearsDiff, int *monthsDiff, int *daysDiff, int *direction) const;
969
* Returns the difference between this and another date in years, months and days
970
* in the current Calendar System.
972
* The difference is always calculated from the earlier date to the later
973
* date in year, month and day order, with the @p direction parameter
974
* indicating which direction the difference is applied from this date.
975
* In other words, this difference can be added onto the earlier date in
976
* year, month, day order to reach the later date.
978
* For example, the difference between 2010-06-10 and 2012-09-5 is 2 years,
979
* 2 months and 26 days. Note that the difference between two last days of
980
* the month is always 1 month, e.g. 2010-01-31 to 2010-02-28 is 1 month
983
* @see addYears() addMonths() addDays()
984
* @see yearsDifference() monthsDifference() daysDifference()
985
* @param toDate The date to end at
986
* @param yearsDiff Returns number of years difference
987
* @param monthsDiff Returns number of months difference
988
* @param daysDiff Returns number of days difference
989
* @param direction Returns direction of difference, 1 if this Date <= toDate, -1 otherwise
991
void dateDifference(const QDate &toDate,
992
int *yearsDiff, int *monthsDiff, int *daysDiff, int *direction) const;
995
* Returns the difference between this and another date in completed calendar years
996
* in the current Calendar System.
998
* The returned value will be negative if @p toDate < this date.
1000
* For example, the difference between 2010-06-10 and 2012-09-5 is 2 years.
1003
* @see dateDifference() monthsDifference() daysDifference()
1004
* @param toDate The date to end at
1005
* @return The number of years difference
1007
int yearsDifference(const KLocalizedDate &toDate) const;
1010
* Returns the difference between this and another date in completed calendar years
1011
* in the current Calendar System.
1013
* The returned value will be negative if @p toDate < this date.
1015
* For example, the difference between 2010-06-10 and 2012-09-5 is 2 years.
1018
* @see dateDifference() monthsDifference() daysDifference()
1019
* @param toDate The date to end at
1020
* @return The number of years difference
1022
int yearsDifference(const QDate &toDate) const;
1025
* Returns the difference between this and another date in completed calendar months
1026
* in the current Calendar System.
1028
* The returned value will be negative if @p toDate < this date.
1030
* For example, the difference between 2010-06-10 and 2012-09-5 is 26 months.
1031
* Note that the difference between two last days of the month is always 1
1032
* month, e.g. 2010-01-31 to 2010-02-28 is 1 month not 28 days.
1035
* @see dateDifference() yearsDifference() daysDifference()
1036
* @param toDate The date to end at
1037
* @return The number of months difference
1039
int monthsDifference(const KLocalizedDate &toDate) const;
1042
* Returns the difference between this and another date in completed calendar months
1043
* in the current Calendar System.
1045
* The returned value will be negative if @p toDate < this date.
1047
* For example, the difference between 2010-06-10 and 2012-09-5 is 26 months.
1048
* Note that the difference between two last days of the month is always 1
1049
* month, e.g. 2010-01-31 to 2010-02-28 is 1 month not 28 days.
1052
* @see dateDifference() yearsDifference() daysDifference()
1053
* @param toDate The date to end at
1054
* @return The number of months difference
1056
int monthsDifference(const QDate &toDate) const;
1059
* Returns the difference between this and another date in days
1060
* The returned value will be negative if @p toDate < this date.
1063
* @see dateDifference() yearsDifference() monthsDifference()
1064
* @param toDate The date to end at
1065
* @return The number of days difference
1067
int daysDifference(const KLocalizedDate &toDate) const;
1070
* Returns the difference between this and another date in days
1071
* The returned value will be negative if @p toDate < this date.
1074
* @see dateDifference() yearsDifference() monthsDifference()
1075
* @param toDate The date to end at
1076
* @return The number of days difference
1078
int daysDifference(const QDate &toDate) const;
1081
* Returns a KLocalizedDate containing the first day of the currently set year
1083
* @see lastDayOfYear()
1084
* @return The first day of the year
1086
KLocalizedDate firstDayOfYear() const;
1089
* Returns a KLocalizedDate containing the last day of the currently set year
1091
* @see firstDayOfYear()
1092
* @return The last day of the year
1094
KLocalizedDate lastDayOfYear() const;
1097
* Returns a KLocalizedDate containing the first day of the currently set month
1099
* @see lastDayOfMonth()
1100
* @return The first day of the month
1102
KLocalizedDate firstDayOfMonth() const;
1105
* Returns a KLocalizedDate containing the last day of the currently set month
1107
* @see firstDayOfMonth()
1108
* @return The last day of the month
1110
KLocalizedDate lastDayOfMonth() const;
1113
* KLocalizedDate equality operator
1115
* @param other the date to compare
1117
bool operator==(const KLocalizedDate &other) const;
1120
* QDate equality operator
1122
* @param other the date to compare
1124
bool operator==(const QDate &other) const;
1127
* KLocalizedDate inequality operator
1129
* @param other the date to compare
1131
bool operator!=(const KLocalizedDate &other) const;
1134
* QDate inequality operator
1136
* @param other the date to compare
1138
bool operator!=(const QDate &other) const;
1141
* KLocalizedDate less than operator
1143
* @param other the date to compare
1145
bool operator<(const KLocalizedDate &other) const;
1148
* QDate less than operator
1150
* @param other the date to compare
1152
bool operator<(const QDate &other) const;
1155
* KLocalizedDate less than or equal to operator
1157
* @param other the date to compare
1159
bool operator<=(const KLocalizedDate &other) const;
1162
* QDate less than or equal to operator
1164
* @param other the date to compare
1166
bool operator<=(const QDate &other) const;
1169
* KLocalizedDate greater than operator
1171
* @param other the date to compare
1173
bool operator>(const KLocalizedDate &other) const;
1176
* QDate greater than operator
1178
* @param other the date to compare
1180
bool operator>(const QDate &other) const;
1183
* KLocalizedDate greater than or equal to operator
1185
* @param other the date to compare
1187
bool operator>=(const KLocalizedDate &other) const;
1190
* QDate greater than or equal to operator
1192
* @param other the date to compare
1194
bool operator>=(const QDate &other) const;
1198
friend QDataStream KDECORE_EXPORT &operator<<(QDataStream &out, const KLocalizedDate &date);
1199
friend QDataStream KDECORE_EXPORT &operator>>(QDataStream &in, KLocalizedDate &date);
1200
friend QDebug KDECORE_EXPORT operator<<(QDebug, const KLocalizedDate &);
1202
QSharedDataPointer<KLocalizedDatePrivate> d;
1205
Q_DECLARE_METATYPE(KLocalizedDate)
1208
* Data stream output operator
1210
* @param other the date to compare
1212
QDataStream KDECORE_EXPORT &operator<<(QDataStream &out, const KLocalizedDate &date);
1215
* Data stream input operator
1217
* @param other the date to compare
1219
QDataStream KDECORE_EXPORT &operator>>(QDataStream &in, KLocalizedDate &date);
1222
* Debug stream output operator
1224
* @param other the date to print
1226
QDebug KDECORE_EXPORT operator<<(QDebug, const KLocalizedDate &);
added
removed
kdecore/date/klocalizeddate.h
