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