1 /* 2 Copyright (c) 2002 Carlos Moro <cfmoro@correo.uniovi.es> 3 Copyright (c) 2002-2003 Hans Petter Bieker <bieker@kde.org> 4 Copyright 2007, 2009, 2010 John Layt <john@layt.net> 5 6 This library is free software; you can redistribute it and/or 7 modify it under the terms of the GNU Library General Public 8 License as published by the Free Software Foundation; either 9 version 2 of the License, or (at your option) any later version. 10 11 This library is distributed in the hope that it will be useful, 12 but WITHOUT ANY WARRANTY; without even the implied warranty of 13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 14 Library General Public License for more details. 15 16 You should have received a copy of the GNU Library General Public License 17 along with this library; see the file COPYING.LIB. If not, write to 18 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, 19 Boston, MA 02110-1301, USA. 20 */ 21 22 #ifndef KCALENDARSYSTEM_H 23 #define KCALENDARSYSTEM_H 24 25 #include <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 */ 54 enum MonthNameFormat { 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 */ 65 enum WeekDayNameFormat { 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 */ isValid(const QDate & date)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 setYMD(QDate & date,int y,int m,int d)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 */ addDays(const QDate & date,int ndays)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 */ daysDifference(const QDate & fromDate,const QDate & toDate)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 */ week(const QDate & date,int * yearNum)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 dayOfWeekString(const QDate & date)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 daysInWeekString(const QDate & date)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, 1283 KLocale::DateTimeComponentFormat format = KLocale::DefaultComponentFormat, 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 */ weekStartDay()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 */ weekDayOfPray()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 1605