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