KDE 4.7 PyKDE API Reference

- KDE's Python API

# KLocalizedDate Class Reference

`from PyKDE4.kdecore import *`

## Detailed Description

A class representing a date localized using the local calendar system, language and formats

Topics: - intro - calsys - custom - formatting - maths

Introduction

This class provides a simple and convenient way to localize dates

Calendar System

KDE supports the use of different calendar systems.

Default and Custom Locale and Calendar System

In most cases you will want to use the default Global Locale and Calendar System, in which case you need only create a default KLocalizedDate. If however you specifically need a different Calendar System or Locale settings then you need to take some extra steps.

The simplest method is just changing the Calendar System while keeping the current Locale settings. This is easily done using setCalendarSystem() which will copy the current Locale being used and apply this to the new Calendar System. Note this means any changes to the old locale settings, either the Global Locale or a custom Locale (see below) will not apply to that date instance.

You may however wish to use a custom Locale with the Calendar System. For example, if you want your app to normally show dates using the Global Locale and Calendar System, but wish to show an info box with the Islamic date in Arabic language and format, then you need a custom Locale to do this.

     KLocale *myLocale = new KLocale("myapp", "ar", "eg");
     KCalendarSystem *myCalendar = KCalendarSystem.create(KLocale.IslamicCivilCalendar, myLocale);
     KLocalizedDate myDate(QDate(2010,1,1), myCalendar);

In this case you are responsible for the memory management of the KLocale and KCalendarSystem. This allows you to reuse this calendar across multiple date instances without it being deleted under you. It also allows you to change any setting in the Locale and have it apply across all those date instances.

Warning:
  Don't try changing the Calendar System via your Locale instance, your KCalendarSystem instance will be deleted and all the dates will be invalid!

See also:

Date Formatting

When you display dates or date components to users in a GUI, they will expect them to be displayed in their language and digit set following their local date formatting conventions. Directly displaying values returned by the normal date component methods such as day() will not conform to these expectations, so you need to use different methods to obtain the localized string form of the date or component.

You can either format the entire date, or just a single component of the date such as the month or day.

When formatting a full date, it is preferred to use one of the standard date formats defined in the Locale, although you can provide your own format in either the KDE, POSIX, or UNICODE standards.

See also:
  formatDate() formatDate()

Date Parsing

Basic concepts on date parsing, then full details on KLocale.ReadDateFlags formats, definging your own date format strings, and setting how strictly the format is appplied.

You can choose how strictly a date format is applied in parsing. Currently only liberal Parsing is supported.

The KLocale.LiberalParsing mode applies the following rules:

1) You must supply a format and string containing at least one of the following combinations to create a valid date:

- a month and day of month
- a day of year
- a ISO week number and day of week

2) If a year number is not supplied then the current year will be assumed.

3) All date components must be separated by a non-numeric character.

4) The format is not applied strictly to the input string:

- extra whitespace is ignored
- leading 0's on numbers are ignored
- capitalisation of literals is ignored

See also:
  readDate()

Date Maths

A full set of date maths functions are provided which operate in a consistent manner, i.e. you can safely round-trip.

## Methods
| __init__ (self, QDate date=QDate(), KCalendarSystem calendar=0)
| __init__ (self, int year, int month, int day, KCalendarSystem calendar=0)
| __init__ (self, KLocalizedDate rhs)
KLocalizedDate | addDays (self, int days)
bool | addDaysTo (self, int days)
KLocalizedDate | addMonths (self, int months)
bool | addMonthsTo (self, int months)
KLocalizedDate | addYears (self, int years)
bool | addYearsTo (self, int years)
KCalendarSystem | calendar (self)
KLocale.CalendarSystem | calendarSystem (self)
QDate | date (self)
| dateDifference (self, KLocalizedDate toDate, int yearsDiff, int monthsDiff, int daysDiff, int direction)
| dateDifference (self, QDate toDate, int yearsDiff, int monthsDiff, int daysDiff, int direction)
int | day (self)
int | dayOfWeek (self)
int | dayOfYear (self)
int | daysDifference (self, KLocalizedDate toDate)
int | daysDifference (self, QDate toDate)
int | daysInMonth (self)
int | daysInWeek (self)
int | daysInYear (self)
QString | eraName (self)
QString | eraYear (self)
KLocalizedDate | firstDayOfMonth (self)
KLocalizedDate | firstDayOfYear (self)
QString | formatDate (self, KLocale.DateFormat dateFormat=KLocale.LongDate)
QString | formatDate (self, QString formatString, KLocale.DateTimeFormatStandard formatStandard=KLocale.KdeFormat)
QString | formatDate (self, KLocale.DateTimeComponent component, KLocale.DateTimeComponentFormat format=KLocale.DefaultComponentFormat, KLocale.WeekNumberSystem weekNumberSystem=KLocale.DefaultWeekNumber)
| getDate (self, int year, int month, int day)
bool | isLeapYear (self)
bool | isNull (self)
bool | isValid (self)
KLocalizedDate | lastDayOfMonth (self)
KLocalizedDate | lastDayOfYear (self)
int | month (self)
int | monthsDifference (self, KLocalizedDate toDate)
int | monthsDifference (self, QDate toDate)
int | monthsInYear (self)
bool | operator != (self, KLocalizedDate other)
bool | operator != (self, QDate other)
bool | operator < (self, KLocalizedDate other)
bool | operator < (self, QDate other)
bool | operator <= (self, KLocalizedDate other)
bool | operator <= (self, QDate other)
bool | operator == (self, KLocalizedDate other)
bool | operator == (self, QDate other)
bool | operator > (self, KLocalizedDate other)
bool | operator > (self, QDate other)
bool | operator >= (self, KLocalizedDate other)
bool | operator >= (self, QDate other)
| setCalendarSystem (self, KLocale.CalendarSystem calendarSystem)
bool | setCurrentDate (self)
bool | setDate (self, QDate date)
bool | setDate (self, int year, int month, int day)
bool | setDate (self, int year, int dayOfYear)
bool | setDate (self, QString eraName, int yearInEra, int month, int day)
bool | setDate (self, KLocale.WeekNumberSystem weekNumberSystem, int year, int weekOfYear, int dayOfWeek)
int | toJulianDay (self)
int | week (self, int yearNum=0)
int | week (self, KLocale.WeekNumberSystem weekNumberSystem, int yearNum=0)
int | weeksInYear (self)
int | weeksInYear (self, KLocale.WeekNumberSystem weekNumberSystem)
int | year (self)
int | yearInEra (self)
int | yearsDifference (self, KLocalizedDate toDate)
int | yearsDifference (self, QDate toDate)
## Static Methods
KLocalizedDate | currentDate ()
KLocalizedDate | fromDate (QDate date)
KLocalizedDate | fromJulianDay (int jd)
KLocalizedDate | readDate (QString dateString, KLocale.DateTimeParseMode parseMode=KLocale.LiberalParsing, KCalendarSystem calendar=0)
KLocalizedDate | readDate (QString dateString, KLocale.ReadDateFlags formatFlags, KLocale.DateTimeParseMode parseMode=KLocale.LiberalParsing, KCalendarSystem calendar=0)
KLocalizedDate | readDate (QString dateString, QString dateFormat, KLocale.DateTimeParseMode parseMode=KLocale.LiberalParsing, KLocale.DateTimeFormatStandard formatStandard=KLocale.KdeFormat, KCalendarSystem calendar=0)

## Method Documentation

__init__ | ( | self, |
|  | QDate | date=QDate(),
|  | KCalendarSystem | calendar=0
| ) |  |  |

Constructs a localized date with the given date.

By default, uses the global Calendar System and Locale.

If you pass in a custom Calendar System then you retain ownership of it and are responsible for deleting it. This allows you to reuse the same custom Calendar System for many localized date instances.

See custom for more details on using custom Calendar Systems.

Parameters:

  | date | the QDate to set the KLocalizedDate to, defaults to invalid date
  | calendar | the calendar system to use, defaults to the global

__init__ | ( | self, |
|  | int | year,
|  | int | month,
|  | int | day,
|  | KCalendarSystem | calendar=0
| ) |  |  |

Constructs a localized date with the given year, month and day.

By default, uses the global Calendar System and Locale.

If you pass in a custom Calendar System then you retain ownership of it and are responsible for deleting it. This allows you to reuse the same custom Calendar System for many localized date instances.

See custom for more details on using custom Calendar Systems.

Parameters:

  | year | the year to set the KLocalizedDate to
  | month | the month to set the KLocalizedDate to
  | day | the day to set the KLocalizedDate to
  | calendar | the calendar system to use, defaults to the global

__init__ | ( | self, |
|  | KLocalizedDate | rhs
| ) |  |  |

Copy constructor

Parameters:

  | rhs | the date to copy

KLocalizedDate addDays | ( | self, |
|  | int | days
| ) |  |  |

Returns a KLocalizedDate containing a date days days later.

See also:
  addDaysTo()

See also:
  addYears() addMonths()

See also:
  dateDifference() yearsDifference()

Parameters:

  | days | number of days to add

Returns:
  The new date, null date if any errors

bool addDaysTo | ( | self, |
|  | int | days
| ) |  |  |

Add days onto this date instance.

If the result of the addition is invalid in the current Calendar System then the date will become invalid.

See also:
  addDays()

See also:
  addYearsTo(), addMonthsTo()

See also:
  dateDifference() yearsDifference()

Parameters:

  | days | The number of days to add

Returns:
  if the resulting date is valid

KLocalizedDate addMonths | ( | self, |
|  | int | months
| ) |  |  |

Returns a KLocalizedDate containing a date months months later.

See also:
  addMonthsTo()

See also:
  addYears() addDays()

See also:
  dateDifference() yearsDifference()

Parameters:

  | months | number of months to add

Returns:
  The new date, null date if any errors

bool addMonthsTo | ( | self, |
|  | int | months
| ) |  |  |

Add months onto this date instance.

If the result of the addition is invalid in the current Calendar System then the date will become invalid.

See also:
  addMonths()

See also:
  addYearsTo() addDaysTo()

See also:
  dateDifference() yearsDifference()

Parameters:

  | months | The number of months to add

Returns:
  if the resulting date is valid

KLocalizedDate addYears | ( | self, |
|  | int | years
| ) |  |  |

Returns a KLocalizedDate containing a date years years later.

See also:
  addYearsTo()

See also:
  addMonths() addDays()

See also:
  dateDifference() yearsDifference()

Parameters:

  | years | The number of years to add

Returns:
  The new date, null date if any errors

bool addYearsTo | ( | self, |
|  | int | years
| ) |  |  |

Add years onto this date instance.

If the result of the addition is invalid in the current Calendar System then the date will become invalid.

See also:
  addYears()

See also:
  addMonthsTo() addDaysTo()

See also:
  dateDifference() yearsDifference()

Parameters:

  | years | The number of years to add

Returns:
  if the resulting date is valid

KCalendarSystem calendar | ( |  | self ) |

Returns a pointer to the Calendar System object used by this date instance.

Usually this will be the Global Calendar System, but this may have been changed.

Normally you will not need to access this object unless the KLocalizedDate API does not provide the methods you require.

See also:
  KCalendarSystem

See also:
  calendarSystem

See also:
  setCalendarSystem

Returns:
  the current calendar system instance

KLocale.CalendarSystem calendarSystem | ( |  | self ) |

Returns the Calendar System used by this localized date instance

See also:
  KLocale.CalendarSystem

See also:
  setCalendarSystem()

Returns:
  the Calendar System currently used

QDate date | ( |  | self ) |

Returns the currently set date as a QDate

Returns:
  the currently set date as a QDate

dateDifference | ( | self, |
|  | KLocalizedDate | toDate,
|  | int | yearsDiff,
|  | int | monthsDiff,
|  | int | daysDiff,
|  | int | direction
| ) |  |  |

Returns the difference between this and another date in years, months and days in the current Calendar System.

The difference is always calculated from the earlier date to the later date in year, month and day order, with the direction parameter indicating which direction the difference is applied from this date. In other words, this difference can be added onto the earlier date in year, month, day order to reach the later date.

For example, the difference between 2010-06-10 and 2012-09-5 is 2 years, 2 months and 26 days. Note that the difference between two last days of the month is always 1 month, e.g. 2010-01-31 to 2010-02-28 is 1 month not 28 days.

See also:
  addYears() addMonths() addDays()

See also:
  yearsDifference() monthsDifference() daysDifference()

Parameters:

  | toDate | The date to end at
  | yearsDiff | Returns number of years difference
  | monthsDiff | Returns number of months difference
  | daysDiff | Returns number of days difference
  | direction | Returns direction of difference, 1 if this Date <= toDate, -1 otherwise

dateDifference | ( | self, |
|  | QDate | toDate,
|  | int | yearsDiff,
|  | int | monthsDiff,
|  | int | daysDiff,
|  | int | direction
| ) |  |  |

Returns the difference between this and another date in years, months and days in the current Calendar System.

The difference is always calculated from the earlier date to the later date in year, month and day order, with the direction parameter indicating which direction the difference is applied from this date. In other words, this difference can be added onto the earlier date in year, month, day order to reach the later date.

For example, the difference between 2010-06-10 and 2012-09-5 is 2 years, 2 months and 26 days. Note that the difference between two last days of the month is always 1 month, e.g. 2010-01-31 to 2010-02-28 is 1 month not 28 days.

See also:
  addYears() addMonths() addDays()

See also:
  yearsDifference() monthsDifference() daysDifference()

Parameters:

  | toDate | The date to end at
  | yearsDiff | Returns number of years difference
  | monthsDiff | Returns number of months difference
  | daysDiff | Returns number of days difference
  | direction | Returns direction of difference, 1 if this Date <= toDate, -1 otherwise

int day | ( |  | self ) |

Returns the day portion of the date in the current calendar system

See formatting for why you should never display this value.

See also:
  formatDate()

Returns:
  the localized day number, 0 if date is invalid

int dayOfWeek | ( |  | self ) |

Returns the weekday number for the date

The weekdays are numbered 1..7 for Monday..Sunday.

This value is not affected by the value of KLocale.weekStartDay()

See formatting for why you should never display this value.

See also:
  formatDate()

Returns:
  day of week number, -1 if date not valid

int dayOfYear | ( |  | self ) |

Returns the day number of year for the date

The days are numbered 1..daysInYear()

See formatting for why you should never display this value.

See also:
  formatDate()

Returns:
  day of year number, -1 if date not valid

int daysDifference | ( | self, |
|  | KLocalizedDate | toDate
| ) |  |  |

Returns the difference between this and another date in days The returned value will be negative if toDate < this date.

See also:
  addDays()

See also:
  dateDifference() yearsDifference() monthsDifference()

Parameters:

  | toDate | The date to end at

Returns:
  The number of days difference

int daysDifference | ( | self, |
|  | QDate | toDate
| ) |  |  |

Returns the difference between this and another date in days The returned value will be negative if toDate < this date.

See also:
  addDays()

See also:
  dateDifference() yearsDifference() monthsDifference()

Parameters:

  | toDate | The date to end at

Returns:
  The number of days difference

int daysInMonth | ( |  | self ) |

Returns the number of days in the month.

See formatting for why you should never display this value.

See also:
  formatDate()

Returns:
  number of days in month, -1 if date invalid

int daysInWeek | ( |  | self ) |

Returns the number of days in the week.

See formatting for why you should never display this value.

See also:
  formatDate()

Returns:
  number of days in week, -1 if date invalid

int daysInYear | ( |  | self ) |

Returns the number of days in the year.

For example, in the Gregorian calendar most years have 365 days but Leap Years have 366 years. Other Calendar Systems have different length years.

See formatting for why you should never display this value.

See also:
  formatDate()

Returns:
  number of days in year, -1 if date invalid

QString eraName | ( |  | self ) |

Returns the Era Name portion of the date in the current calendar system, for example "AD" or "Anno Domini" for the Gregorian calendar and Christian Era.

See formatting for more details on Date Formatting.

See also:
  formatDate()

Returns:
  the localized era name, empty string if date is invalid

QString eraYear | ( |  | self ) |

Returns the Era Year portion of the date in the current calendar system, for example "2000 AD" or "Heisei 22".

See formatting for more details on Date Formatting.

See also:
  formatDate()

Returns:
  the localized era year string, empty string if date is invalid

KLocalizedDate firstDayOfMonth | ( |  | self ) |

Returns a KLocalizedDate containing the first day of the currently set month

See also:
  lastDayOfMonth()

Returns:
  The first day of the month

KLocalizedDate firstDayOfYear | ( |  | self ) |

Returns a KLocalizedDate containing the first day of the currently set year

See also:
  lastDayOfYear()

Returns:
  The first day of the year

QString formatDate | ( | self, |
|  | KLocale.DateFormat | dateFormat=KLocale.LongDate
| ) |  |  |

Returns a Date Component as a localized string in the requested format.

See formatting for more details on Date Formatting.

Each format size may vary depending on Locale and Calendar System but will generally match the format description. Some formats may not be directly valid but a sensible value will always be returned.

For example for 2010-01-01 the KLocale.Month with en_US Locale and Gregorian calendar may return: KLocale.ShortNumber = "1" KLocale.LongNumber = "01" KLocale.NarrowName = "J" KLocale.ShortName = "Jan" KLocale.LongName = "January"

See also:
  formatDate()

Parameters:

  | component | The date component to return
  | format | The format to return the component in
  | weekNumberSystem | To override the default Week Number System to use

Returns:
  The string form of the date component

QString formatDate | ( | self, |
|  | QString | formatString,
|  | KLocale.DateTimeFormatStandard | formatStandard=KLocale.KdeFormat
| ) |  |  |

Returns a Date Component as a localized string in the requested format.

See formatting for more details on Date Formatting.

Each format size may vary depending on Locale and Calendar System but will generally match the format description. Some formats may not be directly valid but a sensible value will always be returned.

For example for 2010-01-01 the KLocale.Month with en_US Locale and Gregorian calendar may return: KLocale.ShortNumber = "1" KLocale.LongNumber = "01" KLocale.NarrowName = "J" KLocale.ShortName = "Jan" KLocale.LongName = "January"

See also:
  formatDate()

Parameters:

  | component | The date component to return
  | format | The format to return the component in
  | weekNumberSystem | To override the default Week Number System to use

Returns:
  The string form of the date component

QString formatDate | ( | self, |
|  | KLocale.DateTimeComponent | component,
|  | KLocale.DateTimeComponentFormat | format=KLocale.DefaultComponentFormat,
|  | KLocale.WeekNumberSystem | weekNumberSystem=KLocale.DefaultWeekNumber
| ) |  |  |

Returns a Date Component as a localized string in the requested format.

See formatting for more details on Date Formatting.

Each format size may vary depending on Locale and Calendar System but will generally match the format description. Some formats may not be directly valid but a sensible value will always be returned.

For example for 2010-01-01 the KLocale.Month with en_US Locale and Gregorian calendar may return: KLocale.ShortNumber = "1" KLocale.LongNumber = "01" KLocale.NarrowName = "J" KLocale.ShortName = "Jan" KLocale.LongName = "January"

See also:
  formatDate()

Parameters:

  | component | The date component to return
  | format | The format to return the component in
  | weekNumberSystem | To override the default Week Number System to use

Returns:
  The string form of the date component

getDate | ( | self, |
|  | int | year,
|  | int | month,
|  | int | day
| ) |  |  |

Returns the year, month and day portion of the date in the current Calendar System.

See formatting for why you should never display this value.

See also:
  setDate()

See also:
  formatDate()

Parameters:

  | year | year number returned in this variable
  | month | month number returned in this variable
  | day | day of month returned in this variable

bool isLeapYear | ( |  | self ) |

Returns whether the currently set date falls in a Leap Year in the current Calendar System.

Returns:
  true if the date falls in a leap year

bool isNull | ( |  | self ) |

Returns whether the date is null, i.e. invalid in any Calendar System.

See also:
  isValid

Returns:
  true if the date is null, false otherwise

bool isValid | ( |  | self ) |

Returns whether the date is valid in the current Calendar System.

See also:
  isNull

Returns:
  true if the date is valid, false otherwise

KLocalizedDate lastDayOfMonth | ( |  | self ) |

Returns a KLocalizedDate containing the last day of the currently set month

See also:
  firstDayOfMonth()

Returns:
  The last day of the month

KLocalizedDate lastDayOfYear | ( |  | self ) |

Returns a KLocalizedDate containing the last day of the currently set year

See also:
  firstDayOfYear()

Returns:
  The last day of the year

int month | ( |  | self ) |

Returns the month portion of the date in the current calendar system

See formatting for why you should never display this value.

See also:
  formatDate()

Returns:
  the localized month number, 0 if date is invalid

int monthsDifference | ( | self, |
|  | KLocalizedDate | toDate
| ) |  |  |

Returns the difference between this and another date in completed calendar months in the current Calendar System.

The returned value will be negative if toDate < this date.

For example, the difference between 2010-06-10 and 2012-09-5 is 26 months. Note that the difference between two last days of the month is always 1 month, e.g. 2010-01-31 to 2010-02-28 is 1 month not 28 days.

See also:
  addMonths()

See also:
  dateDifference() yearsDifference() daysDifference()

Parameters:

  | toDate | The date to end at

Returns:
  The number of months difference

int monthsDifference | ( | self, |
|  | QDate | toDate
| ) |  |  |

Returns the difference between this and another date in completed calendar months in the current Calendar System.

The returned value will be negative if toDate < this date.

For example, the difference between 2010-06-10 and 2012-09-5 is 26 months. Note that the difference between two last days of the month is always 1 month, e.g. 2010-01-31 to 2010-02-28 is 1 month not 28 days.

See also:
  addMonths()

See also:
  dateDifference() yearsDifference() daysDifference()

Parameters:

  | toDate | The date to end at

Returns:
  The number of months difference

int monthsInYear | ( |  | self ) |

Returns number of months in the year

See formatting for why you should never display this value.

See also:
  formatDate()

Returns:
  number of months in the year, -1 if date invalid

bool operator != | ( | self, |
|  | KLocalizedDate | other
| ) |  |  |

QDate inequality operator

Parameters:

  | other | the date to compare

bool operator != | ( | self, |
|  | QDate | other
| ) |  |  |

QDate inequality operator

Parameters:

  | other | the date to compare

bool operator < | ( | self, |
|  | KLocalizedDate | other
| ) |  |  |

QDate less than operator

Parameters:

  | other | the date to compare

bool operator < | ( | self, |
|  | QDate | other
| ) |  |  |

QDate less than operator

Parameters:

  | other | the date to compare

bool operator <= | ( | self, |
|  | KLocalizedDate | other
| ) |  |  |

QDate less than or equal to operator

Parameters:

  | other | the date to compare

bool operator <= | ( | self, |
|  | QDate | other
| ) |  |  |

QDate less than or equal to operator

Parameters:

  | other | the date to compare

bool operator == | ( | self, |
|  | KLocalizedDate | other
| ) |  |  |

QDate equality operator

Parameters:

  | other | the date to compare

bool operator == | ( | self, |
|  | QDate | other
| ) |  |  |

QDate equality operator

Parameters:

  | other | the date to compare

bool operator > | ( | self, |
|  | KLocalizedDate | other
| ) |  |  |

QDate greater than operator

Parameters:

  | other | the date to compare

bool operator > | ( | self, |
|  | QDate | other
| ) |  |  |

QDate greater than operator

Parameters:

  | other | the date to compare

bool operator >= | ( | self, |
|  | KLocalizedDate | other
| ) |  |  |

QDate greater than or equal to operator

Parameters:

  | other | the date to compare

bool operator >= | ( | self, |
|  | QDate | other
| ) |  |  |

QDate greater than or equal to operator

Parameters:

  | other | the date to compare

setCalendarSystem | ( | self, |
|  | KLocale.CalendarSystem | calendarSystem
| ) |  |  |

Set the Calendar System used for this date instance only.

This method is mostly useful for when you quickly want to see what the currently set date would look like in a different Calendar System but using the same Locale.

When the Calendar System is changed, a copy will be taken of the Locale previously used and this copy will be applied to the new Calendar System. Any changes to the old Locale settings, either the Global or a Custom Locale, will not be applied to this date instance.

See custom for more details on using custom Calendar Systems.

See also:
  KLocale.CalendarSystem

See also:
  calendarSystem()

Parameters:

  | calendarSystem | the Calendar System to use

bool setCurrentDate | ( |  | self ) |

Set the date to today's date

See also:
  currentDate()

Returns:
  true if the date is valid, false otherwise

bool setDate | ( | self, |
|  | QDate | date
| ) |  |  |

Set the date using the year, week and day of week.

Currently only the ISO Week Number System is supported.

See also:
  week()

See also:
  dayOfWeek()

Parameters:

  | weekNumberSystem | the week number system to use
  | year | year
  | weekOfYear | week of year
  | dayOfWeek | day of week Mon..Sun (1..7)

Returns:
  true if the date is valid, false otherwise

bool setDate | ( | self, |
|  | int | year,
|  | int | month,
|  | int | day
| ) |  |  |

Set the date using the year, week and day of week.

Currently only the ISO Week Number System is supported.

See also:
  week()

See also:
  dayOfWeek()

Parameters:

  | weekNumberSystem | the week number system to use
  | year | year
  | weekOfYear | week of year
  | dayOfWeek | day of week Mon..Sun (1..7)

Returns:
  true if the date is valid, false otherwise

bool setDate | ( | self, |
|  | int | year,
|  | int | dayOfYear
| ) |  |  |

Set the date using the year, week and day of week.

Currently only the ISO Week Number System is supported.

See also:
  week()

See also:
  dayOfWeek()

Parameters:

  | weekNumberSystem | the week number system to use
  | year | year
  | weekOfYear | week of year
  | dayOfWeek | day of week Mon..Sun (1..7)

Returns:
  true if the date is valid, false otherwise

bool setDate | ( | self, |
|  | QString | eraName,
|  | int | yearInEra,
|  | int | month,
|  | int | day
| ) |  |  |

Set the date using the year, week and day of week.

Currently only the ISO Week Number System is supported.

See also:
  week()

See also:
  dayOfWeek()

Parameters:

  | weekNumberSystem | the week number system to use
  | year | year
  | weekOfYear | week of year
  | dayOfWeek | day of week Mon..Sun (1..7)

Returns:
  true if the date is valid, false otherwise

bool setDate | ( | self, |
|  | KLocale.WeekNumberSystem | weekNumberSystem,
|  | int | year,
|  | int | weekOfYear,
|  | int | dayOfWeek
| ) |  |  |

Set the date using the year, week and day of week.

Currently only the ISO Week Number System is supported.

See also:
  week()

See also:
  dayOfWeek()

Parameters:

  | weekNumberSystem | the week number system to use
  | year | year
  | weekOfYear | week of year
  | dayOfWeek | day of week Mon..Sun (1..7)

Returns:
  true if the date is valid, false otherwise

int toJulianDay | ( |  | self ) |

Returns the currently set date as a Julian Day number

See also:
  fromJulianDay()

Returns:
  the currently set date as a Julian Day number

int week | ( | self, |
|  | int | yearNum=0
| ) |  |  |

Returns the Week Number for the date in the required Week Number System.

See formatting for why you should never display this value.

Unless you want a specific Week Number System (e.g. ISO Week), you should use the localized Week Number form of week().

If the date falls in the last week of the previous year or the first week of the following year, then the yearNum returned will be set to the appropriate year.

Technically, the ISO Week Number only applies to the ISO/Gregorian Calendar System, but the same rules will be applied to the current Calendar System.

See also:
  weeksInYear()

See also:
  formatDate()

Parameters:

  | weekNumberSystem | the Week Number System to use
  | yearNum | returns the year the date belongs to

Returns:
  week number, -1 if input date invalid

int week | ( | self, |
|  | KLocale.WeekNumberSystem | weekNumberSystem,
|  | int | yearNum=0
| ) |  |  |

Returns the Week Number for the date in the required Week Number System.

See formatting for why you should never display this value.

Unless you want a specific Week Number System (e.g. ISO Week), you should use the localized Week Number form of week().

If the date falls in the last week of the previous year or the first week of the following year, then the yearNum returned will be set to the appropriate year.

Technically, the ISO Week Number only applies to the ISO/Gregorian Calendar System, but the same rules will be applied to the current Calendar System.

See also:
  weeksInYear()

See also:
  formatDate()

Parameters:

  | weekNumberSystem | the Week Number System to use
  | yearNum | returns the year the date belongs to

Returns:
  week number, -1 if input date invalid

int weeksInYear | ( |  | self ) |

Returns the number of Weeks in the currently set year using the required Week Number System.

See formatting for why you should never display this value.

Unless you specifically want a particular Week Number System (e.g. ISO Weeks) you should use the localized number of weeks provided by weeksInYear().

See also:
  week()

See also:
  formatDate()

Parameters:

  | weekNumberSystem | the week number system to use

Returns:
  number of weeks in the year, -1 if date invalid

int weeksInYear | ( | self, |
|  | KLocale.WeekNumberSystem | weekNumberSystem
| ) |  |  |

Returns the number of Weeks in the currently set year using the required Week Number System.

See formatting for why you should never display this value.

Unless you specifically want a particular Week Number System (e.g. ISO Weeks) you should use the localized number of weeks provided by weeksInYear().

See also:
  week()

See also:
  formatDate()

Parameters:

  | weekNumberSystem | the week number system to use

Returns:
  number of weeks in the year, -1 if date invalid

int year | ( |  | self ) |

Returns the year portion of the date in the current calendar system

See formatting for why you should never display this value.

See also:
  formatDate()

Returns:
  the localized year number

int yearInEra | ( |  | self ) |

Returns the Year In Era portion of the date in the current calendar system, for example 1 for "1 BC".

See formatting for why you should never display this value.

See also:
  formatDate()

See also:
  formatYearInEra()

Returns:
  the localized Year In Era number, -1 if date is invalid

int yearsDifference | ( | self, |
|  | KLocalizedDate | toDate
| ) |  |  |

Returns the difference between this and another date in completed calendar years in the current Calendar System.

The returned value will be negative if toDate < this date.

For example, the difference between 2010-06-10 and 2012-09-5 is 2 years.

See also:
  addYears()

See also:
  dateDifference() monthsDifference() daysDifference()

Parameters:

  | toDate | The date to end at

Returns:
  The number of years difference

int yearsDifference | ( | self, |
|  | QDate | toDate
| ) |  |  |

Returns the difference between this and another date in completed calendar years in the current Calendar System.

The returned value will be negative if toDate < this date.

For example, the difference between 2010-06-10 and 2012-09-5 is 2 years.

See also:
  addYears()

See also:
  dateDifference() monthsDifference() daysDifference()

Parameters:

  | toDate | The date to end at

Returns:
  The number of years difference

## Static Method Documentation

KLocalizedDate currentDate | ( |  | ) |

Returns a KLocalizedDate set to today's date in the Global Locale and Calendar System.

See also:
  setCurrentDate()

Returns:
  today's localized date

KLocalizedDate fromDate | ( | QDate | date
| ) |  |  |

Returns a KLocalizedDate set the required date in the Global Locale and Calendar System.

Parameters:

  | date | the date to set to

Returns:
  a localized date

KLocalizedDate fromJulianDay | ( | int | jd
| ) |  |  |

Returns a KLocalizedDate set the required Julian Day number in the Global Locale and Calendar System.

See also:
  toJulianDay()

Parameters:

  | jd | the Julian Day number to set to

Returns:
  a localized date

KLocalizedDate readDate | ( | QString | dateString,
|  | KLocale.DateTimeParseMode | parseMode=KLocale.LiberalParsing,
|  | KCalendarSystem | calendar=0
| ) |  |  |

Converts a localized date string to a KLocalizedDate using either the Global Calendar System and Locale, or the provided Calendar System.

See parsing for more details on Date Parsing from strings.

This method allows you to define your own date format to parse the date string with.

If you require one of the standard any KLocale.ReadDateFlags formats then use one of the other readDate() methods.

Parameters:

  | dateString | the string to parse
  | dateFormat | the date format to try parse the string with
  | parseMode | how strictly to apply the dateFormat to the dateString
  | formatStandard | the standard the dateFormat format uses
  | calendar | the Calendar System to use when parsing the date

Returns:
  the localized date parsed from the string

KLocalizedDate readDate | ( | QString | dateString,
|  | KLocale.ReadDateFlags | formatFlags,
|  | KLocale.DateTimeParseMode | parseMode=KLocale.LiberalParsing,
|  | KCalendarSystem | calendar=0
| ) |  |  |

Converts a localized date string to a KLocalizedDate using either the Global Calendar System and Locale, or the provided Calendar System.

See parsing for more details on Date Parsing from strings.

This method allows you to define your own date format to parse the date string with.

If you require one of the standard any KLocale.ReadDateFlags formats then use one of the other readDate() methods.

Parameters:

  | dateString | the string to parse
  | dateFormat | the date format to try parse the string with
  | parseMode | how strictly to apply the dateFormat to the dateString
  | formatStandard | the standard the dateFormat format uses
  | calendar | the Calendar System to use when parsing the date

Returns:
  the localized date parsed from the string

KLocalizedDate readDate | ( | QString | dateString,
|  | QString | dateFormat,
|  | KLocale.DateTimeParseMode | parseMode=KLocale.LiberalParsing,
|  | KLocale.DateTimeFormatStandard | formatStandard=KLocale.KdeFormat,
|  | KCalendarSystem | calendar=0
| ) |  |  |

Converts a localized date string to a KLocalizedDate using either the Global Calendar System and Locale, or the provided Calendar System.

See parsing for more details on Date Parsing from strings.

This method allows you to define your own date format to parse the date string with.

If you require one of the standard any KLocale.ReadDateFlags formats then use one of the other readDate() methods.

Parameters:

  | dateString | the string to parse
  | dateFormat | the date format to try parse the string with
  | parseMode | how strictly to apply the dateFormat to the dateString
  | formatStandard | the standard the dateFormat format uses
  | calendar | the Calendar System to use when parsing the date

Returns:
  the localized date parsed from the string