KCalendarSystem Class Reference

from PyKDE4.kdecore import *

Detailed Description

KCalendarSystem abstract base class, provides support for local Calendar Systems in KDE

Derived classes must be created through the create() static method

Enumerations
MonthNameFormat	{ ShortName, LongName, ShortNamePossessive, LongNamePossessive }
StringFormat	{ ShortFormat, LongFormat }
WeekDayNameFormat	{ ShortDayName, LongDayName }
Methods
	__init__ (self, KLocale locale=0)
	__init__ (self, KCalendarSystem a0)
	__init__ (self, KSharedPtr config, KLocale locale=0)
QDate	addDays (self, QDate date, int ndays)
QDate	addMonths (self, QDate date, int nmonths)
QDate	addYears (self, QDate date, int nyears)
QString	calendarType (self)
	dateDifference (self, QDate fromDate, QDate toDate, int yearsDiff, int monthsDiff, int daysDiff, int direction)
bool, int jd	dateToJulianDay (self, int year, int month, int day)
int	day (self, QDate date)
int	dayOfWeek (self, QDate date)
QString	dayOfWeekString (self, QDate pDate)
int	dayOfYear (self, QDate date)
QString	dayOfYearString (self, QDate pDate, KCalendarSystem.StringFormat format=KCalendarSystem.LongFormat)
QString	dayString (self, QDate pDate, KCalendarSystem.StringFormat format=KCalendarSystem.LongFormat)
int, int iLength	dayStringToInteger (self, QString sNum)
int	daysDifference (self, QDate fromDate, QDate toDate)
int	daysInMonth (self, QDate date)
int	daysInMonth (self, int year, int month)
QString	daysInMonthString (self, QDate pDate, KCalendarSystem.StringFormat format=KCalendarSystem.LongFormat)
int	daysInWeek (self, QDate date)
QString	daysInWeekString (self, QDate date)
int	daysInYear (self, QDate date)
int	daysInYear (self, int year)
QString	daysInYearString (self, QDate pDate, KCalendarSystem.StringFormat format=KCalendarSystem.LongFormat)
QDate	earliestValidDate (self)
QDate	epoch (self)
QString	eraName (self, QDate date, KCalendarSystem.StringFormat format=KCalendarSystem.ShortFormat)
QString	eraYear (self, QDate date, KCalendarSystem.StringFormat format=KCalendarSystem.ShortFormat)
QString	formatDate (self, QDate fromDate, KLocale.DateFormat toFormat=KLocale.LongDate)
QString	formatDate (self, QDate fromDate, QString toFormat, KLocale.DateTimeFormatStandard formatStandard=KLocale.KdeFormat)
QString	formatDate (self, QDate fromDate, QString toFormat, KLocale.DigitSet digitSet, KLocale.DateTimeFormatStandard formatStandard=KLocale.KdeFormat)
	getDate (self, QDate date, int year, int month, int day)
bool	isLeapYear (self, int year)
bool	isLeapYear (self, QDate date)
bool	isLunar (self)
bool	isLunisolar (self)
bool	isProleptic (self)
bool	isSolar (self)
bool	isValid (self, int year, int month, int day)
bool	isValid (self, QDate date)
bool	isValid (self, int year, int dayOfYear)
bool	isValid (self, QString eraName, int yearInEra, int month, int day)
bool	isValidIsoWeekDate (self, int year, int isoWeekNumber, int dayOfIsoWeek)
bool, int year, int month, int day	julianDayToDate (self, int jd)
QDate	latestValidDate (self)
KLocale	locale (self)
int	month (self, QDate date)
QString	monthName (self, int month, int year, KCalendarSystem.MonthNameFormat format=KCalendarSystem.LongName)
QString	monthName (self, QDate date, KCalendarSystem.MonthNameFormat format=KCalendarSystem.LongName)
QString	monthString (self, QDate pDate, KCalendarSystem.StringFormat format=KCalendarSystem.LongFormat)
int, int iLength	monthStringToInteger (self, QString sNum)
int	monthsDifference (self, QDate fromDate, QDate toDate)
int	monthsInYear (self, QDate date)
int	monthsInYear (self, int year)
QString	monthsInYearString (self, QDate pDate, KCalendarSystem.StringFormat format=KCalendarSystem.LongFormat)
QDate, bool ok	readDate (self, QString str)
QDate, bool ok	readDate (self, QString dateString, QString dateFormat)
QDate, bool ok	readDate (self, QString str, KLocale.ReadDateFlags flags)
QDate	readDate (self, QString dateString, QString dateFormat, bool ok, KLocale.DateTimeFormatStandard formatStandard)
bool	setDate (self, QDate date, int year, int month, int day)
bool	setDate (self, QDate date, int year, int dayOfYear)
bool	setDate (self, QDate date, QString eraName, int yearInEra, int month, int day)
bool	setDateIsoWeek (self, QDate date, int year, int isoWeekNumber, int dayOfIsoWeek)
	setHasYear0 (self, bool hasYear0)
	setMaxDaysInWeek (self, int maxDays)
	setMaxMonthsInYear (self, int maxMonths)
bool	setYMD (self, QDate date, int y, int m, int d)
QString	weekDayName (self, int weekDay, KCalendarSystem.WeekDayNameFormat format=KCalendarSystem.LongDayName)
QString	weekDayName (self, QDate date, KCalendarSystem.WeekDayNameFormat format=KCalendarSystem.LongDayName)
int	weekDayOfPray (self)
int, int yearNum	weekNumber (self, QDate date, int yearNum=0)
QString	weekNumberString (self, QDate pDate, KCalendarSystem.StringFormat format=KCalendarSystem.LongFormat)
int	weekStartDay (self)
int	weeksInYear (self, QDate date)
int	weeksInYear (self, int year)
QString	weeksInYearString (self, QDate pDate, KCalendarSystem.StringFormat format=KCalendarSystem.LongFormat)
int	year (self, QDate date)
int	yearInEra (self, QDate date)
QString	yearInEraString (self, QDate date, KCalendarSystem.StringFormat format=KCalendarSystem.ShortFormat)
QString	yearString (self, QDate date, KCalendarSystem.StringFormat format=KCalendarSystem.LongFormat)
int, int iLength	yearStringToInteger (self, QString sNum)
int	yearsDifference (self, QDate fromDate, QDate toDate)
Static Methods
QString	calendarLabel (QString calendarType)
QStringList	calendarSystems ()
KCalendarSystem	create (QString calType=QLatin1String("gregorian"), KLocale locale=0)
KCalendarSystem	create (QString calType, KSharedPtr config, KLocale locale=0)

Method Documentation

__init__	(	self,
		KLocale	locale=0
	)

Constructor of abstract calendar class. This will be called by derived classes.

Parameters:

locale

locale to use for translations. The global locale is used if null.

__init__	(	self,
		KCalendarSystem	a0
	)

__init__	(	self,
		KSharedPtr	config,
		KLocale	locale=0
	)

Constructor of abstract calendar class. This will be called by derived classes.

Parameters:

	config	a configuration file with a 'KCalendarSystem %calendarName' group detailing locale-related preferences (such as era options). The global config is used if null.
	locale	locale to use for translations. The global locale is used if null.

QDate addDays	(	self,
		QDate	date,
		int	ndays
	)

Returns a QDate containing a date ndays days later.

Parameters:

	date	The old date
	ndays	number of days to add

Returns:: The new date, null date if any errors

QDate addMonths	(	self,
		QDate	date,
		int	nmonths
	)

Returns a QDate containing a date nmonths months later.

Parameters:

	date	The old date
	nmonths	number of months to add

Returns:: The new date, null date if any errors

QDate addYears	(	self,
		QDate	date,
		int	nyears
	)

Returns a QDate containing a date nyears years later.

Parameters:

	date	The old date
	nyears	The number of years to add

Returns:: The new date, null date if any errors

QString calendarType ( self )

Abstract method:: This method is abstract and can be overridden but not called directly.

Returns the calendar system type.

Returns:: type of calendar system

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

Returns the difference between two dates in years, months and days. The difference is always caculated 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 the toDate.

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.

Parameters:

	fromDate	The date to start from
	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 fromDate <= toDate, -1 otherwise

bool, int jd dateToJulianDay	(	self,
		int	year,
		int	month,
		int	day
	)

Abstract method:: This method is abstract and can be overridden but not called directly.

Internal method to convert YMD values for this calendar system into a Julian Day number.

All calendar system implementations MUST implement julianDayToDate and dateToJulianDay methods as all other methods can be expressed as functions of these. Does no internal validity checking.

See also:: KCalendarSystem.julianDayToDate

Parameters:

	year	year number
	month	month number
	day	day of month
	jd	Julian day number returned in this variable

Returns:: true if the date is valid, false otherwise

int day	(	self,
		QDate	date
	)

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

Parameters:

date

date to return day for

Returns:: day of the month, 0 if input date is invalid

int dayOfWeek	(	self,
		QDate	date
	)

Returns the weekday number for the given date

Parameters:

date

the date to obtain day from

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

QString dayOfWeekString	(	self,
		QDate	pDate
	)

Since:: 4.4

Converts a date into a day of week literal

Parameters:

pDate

The date to convert

Returns:: The day of week literal of the date, empty string if any error

See also:: dayOfWeek()

int dayOfYear	(	self,
		QDate	date
	)

Returns the day number of year for the given date

Parameters:

date

the date to obtain day from

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

QString dayOfYearString	(	self,
		QDate	pDate,
		KCalendarSystem.StringFormat	format=KCalendarSystem.LongFormat
	)

Since:: 4.4

Converts a date into a day of year literal

Parameters:

	pDate	The date to convert
	format	The format to return, either short or long

Returns:: The day of year literal of the date, empty string if any error

See also:: dayOfYear()

QString dayString	(	self,
		QDate	pDate,
		KCalendarSystem.StringFormat	format=KCalendarSystem.LongFormat
	)

Converts a date into a day literal

Parameters:

	pDate	The date to convert
	format	The format to return, either short or long

Returns:: The day literal of the date, empty string if any error

See also:: day()

int, int iLength dayStringToInteger	(	self,
		QString	sNum
	)

Deprecated:

Converts a day literal of a part of a string into a integer starting at the beginning of the string

Parameters:

	sNum	The string to parse
	iLength	The number of QChars used, and 0 if no valid symbols was found in the string

Returns:: An integer corresponding to the day

int daysDifference	(	self,
		QDate	fromDate,
		QDate	toDate
	)

Returns the difference between two dates in days The returned value will be negative if fromDate > toDate.

Parameters:

	fromDate	The date to start from
	toDate	The date to end at

Returns:: The number of days difference

int daysInMonth	(	self,
		QDate	date
	)

Since:: 4.5

Returns the number of days in the given month.

Parameters:

	year	the year the month is in
	month	the month

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

int daysInMonth	(	self,
		int	year,
		int	month
	)

Since:: 4.5

Returns the number of days in the given month.

Parameters:

	year	the year the month is in
	month	the month

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

QString daysInMonthString	(	self,
		QDate	pDate,
		KCalendarSystem.StringFormat	format=KCalendarSystem.LongFormat
	)

Since:: 4.4

Returns the days in month for a date as a numeric string

Parameters:

	pDate	The date to convert
	format	The format to return, either short or long

Returns:: The days in month literal of the date, empty string if any error

See also:: daysInMonth()

int daysInWeek	(	self,
		QDate	date
	)

Returns the number of days in the given week.

Parameters:

date

the date to obtain week from

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

QString daysInWeekString	(	self,
		QDate	date
	)

Since:: 4.4

Returns the days in week for a date as a numeric string

Parameters:

date

The date to convert

Returns:: The days in week literal of the date, empty string if any error

See also:: daysInWeek()

int daysInYear	(	self,
		QDate	date
	)

Since:: 4.5

Returns the number of days in the given year.

Parameters:

year

the year

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

int daysInYear	(	self,
		int	year
	)

Since:: 4.5

Returns the number of days in the given year.

Parameters:

year

the year

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

QString daysInYearString	(	self,
		QDate	pDate,
		KCalendarSystem.StringFormat	format=KCalendarSystem.LongFormat
	)

Since:: 4.4

Returns the days in year for a date as a numeric string

Parameters:

	pDate	The date to convert
	format	The format to return, either short or long

Returns:: The days in year literal of the date, empty string if any error

See also:: daysInYear()

QDate earliestValidDate ( self )

Returns the earliest date valid in this calendar system implementation.

If the calendar system is proleptic then this may be before epoch.

See also:: KCalendarSystem.epoch

See also:: KCalendarSystem.latestValidDate

Returns:: date the earliest valid date

QDate epoch ( self )

Returns a QDate holding the epoch of the calendar system. Usually YMD of 1/1/1, access the returned QDates method toJulianDay() if you require the actual Julian day number. Note: a particular calendar system implementation may not include the epoch in its supported range, or the calendar system may be proleptic in which case it supports dates before the epoch.

See also:: KCalendarSystem.earliestValidDate

See also:: KCalendarSystem.latestValidDate

See also:: KCalendarSystem.isProleptic

See also:: KCalendarSystem.isValid

Returns:: epoch of calendar system

QString eraName	(	self,
		QDate	date,
		KCalendarSystem.StringFormat	format=KCalendarSystem.ShortFormat
	)

Since:: 4.5

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

Parameters:

	date	date to return Era Name for
	format	format to return, either short or long

Returns:: era name, empty string if input date is invalid

QString eraYear	(	self,
		QDate	date,
		KCalendarSystem.StringFormat	format=KCalendarSystem.ShortFormat
	)

Since:: 4.5

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

Parameters:

	date	date to return Era Year for
	format	format to return, either short or long

Returns:: era name, empty string if input date is invalid

QString formatDate	(	self,
		QDate	fromDate,
		KLocale.DateFormat	toFormat=KLocale.LongDate
	)

Since:: 4.4

Returns a string formatted to the given format string and Digit Set. Only use this version if you need control over the Digit Set and do not want to use the locale Digit Set.

See also:: formatDate

Parameters:

	fromDate	the date to be formatted
	toFormat	the date format to use
	digitSet	the Digit Set to format the date in
	formatStandard	the standard the date format uses, defaults to KDE Standard

Returns:: The date as a string

QString formatDate	(	self,
		QDate	fromDate,
		QString	toFormat,
		KLocale.DateTimeFormatStandard	formatStandard=KLocale.KdeFormat
	)

Since:: 4.4

Returns a string formatted to the given format string and Digit Set. Only use this version if you need control over the Digit Set and do not want to use the locale Digit Set.

See also:: formatDate

Parameters:

	fromDate	the date to be formatted
	toFormat	the date format to use
	digitSet	the Digit Set to format the date in
	formatStandard	the standard the date format uses, defaults to KDE Standard

Returns:: The date as a string

QString formatDate	(	self,
		QDate	fromDate,
		QString	toFormat,
		KLocale.DigitSet	digitSet,
		KLocale.DateTimeFormatStandard	formatStandard=KLocale.KdeFormat
	)

Since:: 4.4

Returns a string formatted to the given format string and Digit Set. Only use this version if you need control over the Digit Set and do not want to use the locale Digit Set.

See also:: formatDate

Parameters:

	fromDate	the date to be formatted
	toFormat	the date format to use
	digitSet	the Digit Set to format the date in
	formatStandard	the standard the date format uses, defaults to KDE Standard

Returns:: The date as a string

getDate	(	self,
		QDate	date,
		int	year,
		int	month,
		int	day
	)

Since:: 4.5

Returns the year, month and day portion of a given date in the current calendar system

Parameters:

	date	date to get year, month and day for
	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,
		int	year
	)

Abstract method:: This method is abstract and can be overridden but not called directly.

Returns whether a given date falls in a leap year.

Input date must be checked for validity in current Calendar System prior to calling, no validity checking performed in this routine, behaviour is undefined in invalid case.

Parameters:

date

the date to check

Returns:: true if the date falls in a leap year, false otherwise

bool isLeapYear	(	self,
		QDate	date
	)

Returns whether a given date falls in a leap year.

Input date must be checked for validity in current Calendar System prior to calling, no validity checking performed in this routine, behaviour is undefined in invalid case.

Parameters:

date

the date to check

Returns:: true if the date falls in a leap year, false otherwise

bool isLunar ( self )

Abstract method:: This method is abstract and can be overridden but not called directly.

Returns whether the calendar is lunar based.

Returns:: true if the calendar is lunar based, false if not

bool isLunisolar ( self )

Abstract method:: This method is abstract and can be overridden but not called directly.

Returns whether the calendar is lunisolar based.

Returns:: true if the calendar is lunisolar based, false if not

bool isProleptic ( self )

Abstract method:: This method is abstract and can be overridden but not called directly.

Returns whether the calendar system is proleptic, i.e. whether dates before the epoch are supported.

See also:: KCalendarSystem.epoch

Returns:: true if the calendar system is proleptic, false if not

bool isSolar ( self )

Abstract method:: This method is abstract and can be overridden but not called directly.

Returns whether the calendar is solar based.

Returns:: true if the calendar is solar based, false if not

bool isValid	(	self,
		int	year,
		int	month,
		int	day
	)

Abstract method:: This method is abstract and can be overridden but not called directly.

Returns whether a given date is valid in this calendar system.

Parameters:

date

the date to check

Returns:: true if the date is valid, false otherwise

bool isValid	(	self,
		QDate	date
	)

Returns whether a given date is valid in this calendar system.

Parameters:

date

the date to check

Returns:: true if the date is valid, false otherwise

bool isValid	(	self,
		int	year,
		int	dayOfYear
	)

Returns whether a given date is valid in this calendar system.

Parameters:

date

the date to check

Returns:: true if the date is valid, false otherwise

bool isValid	(	self,
		QString	eraName,
		int	yearInEra,
		int	month,
		int	day
	)

Returns whether a given date is valid in this calendar system.

Parameters:

date

the date to check

Returns:: true if the date is valid, false otherwise

bool isValidIsoWeekDate	(	self,
		int	year,
		int	isoWeekNumber,
		int	dayOfIsoWeek
	)

Since:: 4.4

Returns whether a given date is valid in this calendar system.

Parameters:

	year	the year portion of the date to check
	isoWeekNumber	the ISO week portion of the date to check
	dayOfIsoWeek	the day of week portion of the date to check

Returns:: true if the date is valid, false otherwise

bool, int year, int month, int day julianDayToDate	(	self,
		int	jd
	)

Abstract method:: This method is abstract and can be overridden but not called directly.

Internal method to convert a Julian Day number into the YMD values for this calendar system.

All calendar system implementations MUST implement julianDayToDate and dateToJulianDay methods as all other methods can be expressed as functions of these. Does no internal validity checking.

See also:: KCalendarSystem.dateToJulianDay

Parameters:

	jd	Julian day number to convert to date
	year	year number returned in this variable
	month	month number returned in this variable
	day	day of month returned in this variable

Returns:: true if the date is valid, false otherwise

QDate latestValidDate ( self )

Returns the latest date valid in this calendar system implementation.

See also:: KCalendarSystem.epoch

See also:: KCalendarSystem.earliestValidDate

Returns:: date the latest valid date

KLocale locale ( self )

Returns the locale used for translations and formats for this calendar system instance. This allows a calendar system instance to be independent of the global translations and formats if required. All implementations must refer to this locale.

Only for internal calendar system use; if public access is required then provide public methods only for those methods actually required. Any app that creates an instance with its own locale overriding global will have the original handle to the locale and can manipulate it that way if required, e.g. to change default date format. Only expose those methods that library widgets require access to internally.

See also:: KCalendarSystem.formatDate

See also:: KLocale.formatDate

See also:: KCalendarSystem.weekStartDay

See also:: KLocale.weekStartDay

See also:: KCalendarSystem.readDate

See also:: KLoacle.readDate

Returns:: locale to use

int month	(	self,
		QDate	date
	)

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

Parameters:

date

date to return month for

Returns:: month of year, 0 if input date is invalid

QString monthName	(	self,
		int	month,
		int	year,
		KCalendarSystem.MonthNameFormat	format=KCalendarSystem.LongName
	)

Abstract method:: This method is abstract and can be overridden but not called directly.

Gets specific calendar type month name for a given date

Parameters:

	date	date to obtain month from
	format	specifies whether the short month name or long month name should be used

Returns:: name of the month, empty string if any error

QString monthName	(	self,
		QDate	date,
		KCalendarSystem.MonthNameFormat	format=KCalendarSystem.LongName
	)

Gets specific calendar type month name for a given date

Parameters:

	date	date to obtain month from
	format	specifies whether the short month name or long month name should be used

Returns:: name of the month, empty string if any error

QString monthString	(	self,
		QDate	pDate,
		KCalendarSystem.StringFormat	format=KCalendarSystem.LongFormat
	)

Converts a date into a month literal

Parameters:

	pDate	The date to convert
	format	The format to return, either short or long

Returns:: The month literal of the date, empty string if any error

See also:: month()

int, int iLength monthStringToInteger	(	self,
		QString	sNum
	)

Deprecated:

Converts a month literal of a part of a string into a integer starting at the beginning of the string

Parameters:

	sNum	The string to parse
	iLength	The number of QChars used, and 0 if no valid symbols was found in the string

Returns:: An integer corresponding to the month

int monthsDifference	(	self,
		QDate	fromDate,
		QDate	toDate
	)

Returns the difference between two dates in completed calendar months The returned value will be negative if fromDate > toDate.

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.

Parameters:

	fromDate	The date to start from
	toDate	The date to end at

Returns:: The number of months difference

int monthsInYear	(	self,
		QDate	date
	)

Since:: 4.5

Returns number of months in the given year

Parameters:

year

the required year

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

int monthsInYear	(	self,
		int	year
	)

Since:: 4.5

Returns number of months in the given year

Parameters:

year

the required year

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

QString monthsInYearString	(	self,
		QDate	pDate,
		KCalendarSystem.StringFormat	format=KCalendarSystem.LongFormat
	)

Since:: 4.4

Returns the months in year for a date as a numeric string

Parameters:

	pDate	The date to convert
	format	The format to return, either short or long

Returns:: The months in year literal of the date, empty string if any error

See also:: monthsInYear()

QDate, bool ok readDate	(	self,
		QString	str
	)

Converts a localized date string to a QDate, using the specified format. You will usually not want to use this method.

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

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

All date componants must be separated by a non-numeric character.

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

The allowed format componants are almost the same as the formatDate() function. The following date componants will be read:

%Y the whole year (e.g. "1984" for 1984)

%y the lower 2 digits of the year (e.g. "84" for 1984)

%EY the full local era year (e.g. "2000 AD")

%EC the era name short form (e.g. "AD")

%Ey the year in era to 1 digit (e.g. 1 or 2000)

%m the month number to two digits (January="01", December="12")

%n the month number (January="1", December="12")

%d the day number of the month to two digits (e.g. "01" on the first of March)

%e the day number of the month (e.g. "1" on the first of March)

%B the month name long form (e.g. "January")

%b the month name short form (e.g. "Jan" for January)

%h the month name short form (e.g. "Jan" for January)

%A the weekday name long form (e.g. "Wednesday" for Wednesday)

%a the weekday name short form (e.g. "Wed" for Wednesday)

%j the day of the year number to three digits (e.g. "001" for 1 Jan)

%V the ISO week of the year number to two digits (e.g. "01" for ISO Week 1)

%u the day of the week number (e.g. "1" for Monday)

The following date componants are NOT supported:

%C the 'century' portion of the year (e.g. "19" for 1984, "5" for 584, "" for 84)

%G the year number in long form of the ISO week of the year (e.g. "2004" for 1 Jan 2005)

%g the year number in short form of the ISO week of the year (e.g. "04" for 1 Jan 2005)

%D the US short date format (e.g. "%m/%d/%y")

%F the ISO short date format (e.g. "%Y-%m-%d")

%x the KDE locale short date format

%% the literal "%"

%t a tab character

Parameters:

	dateString	the string to convert
	dateFormat	the date format to use
	ok	if non-null, will be set to true if the date is valid, false if invalid
	formatStandard	the standard the date format uses

Returns:: the string converted to a QDate

See also:: formatDate

See also:: KLocale.readDate

QDate, bool ok readDate	(	self,
		QString	dateString,
		QString	dateFormat
	)

Converts a localized date string to a QDate, using the specified format. You will usually not want to use this method.

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

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

All date componants must be separated by a non-numeric character.

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

The allowed format componants are almost the same as the formatDate() function. The following date componants will be read:

%Y the whole year (e.g. "1984" for 1984)

%y the lower 2 digits of the year (e.g. "84" for 1984)

%EY the full local era year (e.g. "2000 AD")

%EC the era name short form (e.g. "AD")

%Ey the year in era to 1 digit (e.g. 1 or 2000)

%m the month number to two digits (January="01", December="12")

%n the month number (January="1", December="12")

%d the day number of the month to two digits (e.g. "01" on the first of March)

%e the day number of the month (e.g. "1" on the first of March)

%B the month name long form (e.g. "January")

%b the month name short form (e.g. "Jan" for January)

%h the month name short form (e.g. "Jan" for January)

%A the weekday name long form (e.g. "Wednesday" for Wednesday)

%a the weekday name short form (e.g. "Wed" for Wednesday)

%j the day of the year number to three digits (e.g. "001" for 1 Jan)

%V the ISO week of the year number to two digits (e.g. "01" for ISO Week 1)

%u the day of the week number (e.g. "1" for Monday)

The following date componants are NOT supported:

%C the 'century' portion of the year (e.g. "19" for 1984, "5" for 584, "" for 84)

%G the year number in long form of the ISO week of the year (e.g. "2004" for 1 Jan 2005)

%g the year number in short form of the ISO week of the year (e.g. "04" for 1 Jan 2005)

%D the US short date format (e.g. "%m/%d/%y")

%F the ISO short date format (e.g. "%Y-%m-%d")

%x the KDE locale short date format

%% the literal "%"

%t a tab character

Parameters:

	dateString	the string to convert
	dateFormat	the date format to use
	ok	if non-null, will be set to true if the date is valid, false if invalid
	formatStandard	the standard the date format uses

Returns:: the string converted to a QDate

See also:: formatDate

See also:: KLocale.readDate

QDate, bool ok readDate	(	self,
		QString	str,
		KLocale.ReadDateFlags	flags
	)

Converts a localized date string to a QDate, using the specified format. You will usually not want to use this method.

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

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

All date componants must be separated by a non-numeric character.

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

The allowed format componants are almost the same as the formatDate() function. The following date componants will be read:

%Y the whole year (e.g. "1984" for 1984)

%y the lower 2 digits of the year (e.g. "84" for 1984)

%EY the full local era year (e.g. "2000 AD")

%EC the era name short form (e.g. "AD")

%Ey the year in era to 1 digit (e.g. 1 or 2000)

%m the month number to two digits (January="01", December="12")

%n the month number (January="1", December="12")

%d the day number of the month to two digits (e.g. "01" on the first of March)

%e the day number of the month (e.g. "1" on the first of March)

%B the month name long form (e.g. "January")

%b the month name short form (e.g. "Jan" for January)

%h the month name short form (e.g. "Jan" for January)

%A the weekday name long form (e.g. "Wednesday" for Wednesday)

%a the weekday name short form (e.g. "Wed" for Wednesday)

%j the day of the year number to three digits (e.g. "001" for 1 Jan)

%V the ISO week of the year number to two digits (e.g. "01" for ISO Week 1)

%u the day of the week number (e.g. "1" for Monday)

The following date componants are NOT supported:

%C the 'century' portion of the year (e.g. "19" for 1984, "5" for 584, "" for 84)

%G the year number in long form of the ISO week of the year (e.g. "2004" for 1 Jan 2005)

%g the year number in short form of the ISO week of the year (e.g. "04" for 1 Jan 2005)

%D the US short date format (e.g. "%m/%d/%y")

%F the ISO short date format (e.g. "%Y-%m-%d")

%x the KDE locale short date format

%% the literal "%"

%t a tab character

Parameters:

	dateString	the string to convert
	dateFormat	the date format to use
	ok	if non-null, will be set to true if the date is valid, false if invalid
	formatStandard	the standard the date format uses

Returns:: the string converted to a QDate

See also:: formatDate

See also:: KLocale.readDate

QDate readDate	(	self,
		QString	dateString,
		QString	dateFormat,
		bool	ok,
		KLocale.DateTimeFormatStandard	formatStandard
	)

Converts a localized date string to a QDate, using the specified format. You will usually not want to use this method.

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

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

All date componants must be separated by a non-numeric character.

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

The allowed format componants are almost the same as the formatDate() function. The following date componants will be read:

%Y the whole year (e.g. "1984" for 1984)

%y the lower 2 digits of the year (e.g. "84" for 1984)

%EY the full local era year (e.g. "2000 AD")

%EC the era name short form (e.g. "AD")

%Ey the year in era to 1 digit (e.g. 1 or 2000)

%m the month number to two digits (January="01", December="12")

%n the month number (January="1", December="12")

%d the day number of the month to two digits (e.g. "01" on the first of March)

%e the day number of the month (e.g. "1" on the first of March)

%B the month name long form (e.g. "January")

%b the month name short form (e.g. "Jan" for January)

%h the month name short form (e.g. "Jan" for January)

%A the weekday name long form (e.g. "Wednesday" for Wednesday)

%a the weekday name short form (e.g. "Wed" for Wednesday)

%j the day of the year number to three digits (e.g. "001" for 1 Jan)

%V the ISO week of the year number to two digits (e.g. "01" for ISO Week 1)

%u the day of the week number (e.g. "1" for Monday)

The following date componants are NOT supported:

%C the 'century' portion of the year (e.g. "19" for 1984, "5" for 584, "" for 84)

%G the year number in long form of the ISO week of the year (e.g. "2004" for 1 Jan 2005)

%g the year number in short form of the ISO week of the year (e.g. "04" for 1 Jan 2005)

%D the US short date format (e.g. "%m/%d/%y")

%F the ISO short date format (e.g. "%Y-%m-%d")

%x the KDE locale short date format

%% the literal "%"

%t a tab character

Parameters:

	dateString	the string to convert
	dateFormat	the date format to use
	ok	if non-null, will be set to true if the date is valid, false if invalid
	formatStandard	the standard the date format uses

Returns:: the string converted to a QDate

See also:: formatDate

See also:: KLocale.readDate

bool setDate	(	self,
		QDate	date,
		int	year,
		int	month,
		int	day
	)

Since:: 4.5

Set a date using the era, year in era number, month and day

Parameters:

	date	date to change
	eraName	Era string
	year	Year In Era number
	month	Month number
	day	Day Of Month number

Returns:: true if the date is valid, false otherwise

bool setDate	(	self,
		QDate	date,
		int	year,
		int	dayOfYear
	)

Since:: 4.5

Set a date using the era, year in era number, month and day

Parameters:

	date	date to change
	eraName	Era string
	year	Year In Era number
	month	Month number
	day	Day Of Month number

Returns:: true if the date is valid, false otherwise

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

Since:: 4.5

Set a date using the era, year in era number, month and day

Parameters:

	date	date to change
	eraName	Era string
	year	Year In Era number
	month	Month number
	day	Day Of Month number

Returns:: true if the date is valid, false otherwise

bool setDateIsoWeek	(	self,
		QDate	date,
		int	year,
		int	isoWeekNumber,
		int	dayOfIsoWeek
	)

Since:: 4.4

Set a date using the year number, ISO week number and day of week number.

Parameters:

	date	date to change
	year	year
	isoWeekNumber	ISO week of year
	dayOfIsoWeek	day of week Mon..Sun (1..7)

Returns:: true if the date is valid, false otherwise

setHasYear0	(	self,
		bool	hasYear0
	)

Deprecated:

Since:: 4.4

Sets if Calendar System has Year 0 or not

Only for internal calendar system use

setMaxDaysInWeek	(	self,
		int	maxDays
	)

Deprecated:

Sets the maximum number of days in a week

Only for internal calendar system use

setMaxMonthsInYear	(	self,
		int	maxMonths
	)

Deprecated:

Sets the maximum number of months in a year

Only for internal calendar system use

bool setYMD	(	self,
		QDate	date,
		int	y,
		int	m,
		int	d
	)

Deprecated:

Use setDate instead

See also:: KCalendarSystem.setDate

Some implementations reject year range 00 to 99, but extended date ranges now require these to be accepted. Equivalent in QDate is obsoleted.

Changes the date's year, month and day. The range of the year, month and day depends on which calendar is being used.

Parameters:

	date	Date to change
	y	Year
	m	Month number
	d	Day of month

Returns:: true if the date is valid; otherwise returns false.

QString weekDayName	(	self,
		int	weekDay,
		KCalendarSystem.WeekDayNameFormat	format=KCalendarSystem.LongDayName
	)

Abstract method:: This method is abstract and can be overridden but not called directly.

Gets specific calendar type week day name.

Parameters:

	date	the date
	format	specifies whether the short month name or long month name should be used

Returns:: day name, empty string if any error

QString weekDayName	(	self,
		QDate	date,
		KCalendarSystem.WeekDayNameFormat	format=KCalendarSystem.LongDayName
	)

Gets specific calendar type week day name.

Parameters:

	date	the date
	format	specifies whether the short month name or long month name should be used

Returns:: day name, empty string if any error

int weekDayOfPray ( self )

Abstract method:: This method is abstract and can be overridden but not called directly.

Returns the day of the week traditionally associated with religious observance for this calendar system. Note this may not be accurate for the users locale, e.g. Gregorian calendar used in non-Christian countries, in use cases where this could be an issue it is recommended to use KLocale.weekDayOfPray() instead.

Returns:: day number (None = 0, Monday = 1, ..., Sunday = 7)

int, int yearNum weekNumber	(	self,
		QDate	date,
		int	yearNum=0
	)

Returns the ISO week number for the given date.

ISO 8601 defines the first week of the year as the week containing the first Thursday. See http://en.wikipedia.org/wiki/ISO_8601 and http://en.wikipedia.org/wiki/ISO_week_date

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.

Parameters:

	date	the date to obtain week from
	yearNum	returns the year the date belongs to

Returns:: ISO week number, -1 if input date invalid

QString weekNumberString	(	self,
		QDate	pDate,
		KCalendarSystem.StringFormat	format=KCalendarSystem.LongFormat
	)

Since:: 4.4

Converts a date into a week number literal

Parameters:

	pDate	The date to convert
	format	The format to return, either short or long

Returns:: The day literal of the date, empty string if any error

See also:: weekNumber()

int weekStartDay ( self )

Use this to determine which day is the first day of the week.

Uses the calendar system's internal locale set when the instance was created, which ensures that the correct calendar system and locale settings are respected, which would not occur in some cases if using the global locale. Defaults to global locale.

See also:: KLocale.weekStartDay

Returns:: an integer (Monday = 1, ..., Sunday = 7)

int weeksInYear	(	self,
		QDate	date
	)

Returns the number of ISO weeks in the given year.

ISO 8601 defines the first week of the year as the week containing the first Thursday. See http://en.wikipedia.org/wiki/ISO_8601 and http://en.wikipedia.org/wiki/ISO_week_date

Parameters:

year

the year

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

int weeksInYear	(	self,
		int	year
	)

Returns the number of ISO weeks in the given year.

ISO 8601 defines the first week of the year as the week containing the first Thursday. See http://en.wikipedia.org/wiki/ISO_8601 and http://en.wikipedia.org/wiki/ISO_week_date

Parameters:

year

the year

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

QString weeksInYearString	(	self,
		QDate	pDate,
		KCalendarSystem.StringFormat	format=KCalendarSystem.LongFormat
	)

Since:: 4.4

Returns the weeks in year for a date as a numeric string

Parameters:

	pDate	The date to convert
	format	The format to return, either short or long

Returns:: The weeks in year literal of the date, empty string if any error

See also:: weeksInYear()

int year	(	self,
		QDate	date
	)

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

Parameters:

date

date to return year for

Returns:: year, 0 if input date is invalid

int yearInEra	(	self,
		QDate	date
	)

Since:: 4.5

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

Parameters:

date

date to return Year In Era for

Returns:: Year In Era, -1 if input date is invalid

QString yearInEraString	(	self,
		QDate	date,
		KCalendarSystem.StringFormat	format=KCalendarSystem.ShortFormat
	)

Since:: 4.5

Converts a date into a Year In Era literal

Parameters:

	date	date to return Year In Era for
	format	format to return, either short or long

Returns:: Year In Era literal of the date, empty string if any error

QString yearString	(	self,
		QDate	date,
		KCalendarSystem.StringFormat	format=KCalendarSystem.LongFormat
	)

Converts a date into a year literal

Parameters:

	date	date to convert
	format	format to return, either short or long

Returns:: year literal of the date, empty string if any error

See also:: year()

int, int iLength yearStringToInteger	(	self,
		QString	sNum
	)

Deprecated:

Converts a year literal of a part of a string into a integer starting at the beginning of the string

Parameters:

	sNum	The string to parse
	iLength	The number of QChars used, and 0 if no valid symbols was found in the string

Returns:: An integer corresponding to the year

int yearsDifference	(	self,
		QDate	fromDate,
		QDate	toDate
	)

Returns the difference between two dates in completed calendar years. The returned value will be negative if fromDate > toDate.

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

Parameters:

	fromDate	The date to start from
	toDate	The date to end at

Returns:: The number of years difference

Static Method Documentation

QString calendarLabel	(	QString	calendarType
	)

Returns a typographically correct and translated label to display for the calendar system type. Use with calendarSystems() to neatly format labels to display on combo widget of available calendar systems.

Parameters:

calendarType

the specific calendar type to return the label for

Returns:: label for calendar

QStringList calendarSystems ( )

Gets a list of names of supported calendar systems.

Returns:: list of names

KCalendarSystem create	(	QString	calType=QLatin1String("gregorian"),
		KLocale	locale=0
	)

Creates specific calendar type

Parameters:

	calType	string identification of the specific calendar type to be constructed
	config	a configuration file with a 'KCalendarSystem %calendarType' group detailing locale-related preferences (such as era options). The global config is used if null.
	locale	locale to use for translations. The global locale is used if null.

Returns:: a KCalendarSystem object

KCalendarSystem create	(	QString	calType,
		KSharedPtr	config,
		KLocale	locale=0
	)

Creates specific calendar type

Parameters:

	calType	string identification of the specific calendar type to be constructed
	config	a configuration file with a 'KCalendarSystem %calendarType' group detailing locale-related preferences (such as era options). The global config is used if null.
	locale	locale to use for translations. The global locale is used if null.

Returns:: a KCalendarSystem object

Enumeration Documentation

MonthNameFormat

Format for returned month / day name.

Enumerator:

ShortName
LongName
ShortNamePossessive
LongNamePossessive

StringFormat

Format for returned year number / month number / day number as string.

Enumerator:

ShortFormat
LongFormat

WeekDayNameFormat

Format for returned month / day name.

Enumerator:

ShortDayName
LongDayName

KCalendarSystem Class Reference

Detailed Description

Enumerations

Methods

Static Methods

Method Documentation

Static Method Documentation

Enumeration Documentation

Modules