#include <klocalizeddate.h>

Public Member Functions
	KLocalizedDate (const QDate &date=QDate(), const KCalendarSystem *calendar=0)

	KLocalizedDate (int year, int month, int day, const KCalendarSystem *calendar=0)

	KLocalizedDate (const KLocalizedDate &rhs)

	~KLocalizedDate ()

KLocalizedDate	addDays (int days) const

bool	addDaysTo (int days)

KLocalizedDate	addMonths (int months) const

bool	addMonthsTo (int months)

KLocalizedDate	addYears (int years) const

bool	addYearsTo (int years)

const KCalendarSystem *	calendar () const

KLocale::CalendarSystem	calendarSystem ()

QDate	date () const

void	dateDifference (const KLocalizedDate &toDate, int yearsDiff, int monthsDiff, int daysDiff, int direction) const

void	dateDifference (const QDate &toDate, int yearsDiff, int monthsDiff, int daysDiff, int direction) const

int	day () const

int	dayOfWeek () const

int	dayOfYear () const

int	daysDifference (const KLocalizedDate &toDate) const

int	daysDifference (const QDate &toDate) const

int	daysInMonth () const

int	daysInWeek () const

int	daysInYear () const

QString	eraName () const

QString	eraYear () const

KLocalizedDate	firstDayOfMonth () const

KLocalizedDate	firstDayOfYear () const

QString	formatDate (KLocale::DateFormat dateFormat=KLocale::LongDate) const

QString	formatDate (const QString &formatString, KLocale::DateTimeFormatStandard formatStandard=KLocale::KdeFormat) const

QString	formatDate (KLocale::DateTimeComponent component, KLocale::DateTimeComponentFormat format=KLocale::DefaultComponentFormat, KLocale::WeekNumberSystem weekNumberSystem=KLocale::DefaultWeekNumber) const

void	getDate (int year, int month, int *day) const

bool	isLeapYear () const

bool	isNull () const

bool	isValid () const

KLocalizedDate	lastDayOfMonth () const

KLocalizedDate	lastDayOfYear () const

int	month () const

int	monthsDifference (const KLocalizedDate &toDate) const

int	monthsDifference (const QDate &toDate) const

int	monthsInYear () const

bool	operator!= (const KLocalizedDate &other) const

bool	operator!= (const QDate &other) const

bool	operator< (const KLocalizedDate &other) const

bool	operator< (const QDate &other) const

bool	operator<= (const KLocalizedDate &other) const

bool	operator<= (const QDate &other) const

KLocalizedDate &	operator= (const KLocalizedDate &rhs)

KLocalizedDate &	operator= (const QDate &rhs)

bool	operator== (const KLocalizedDate &other) const

bool	operator== (const QDate &other) const

bool	operator> (const KLocalizedDate &other) const

bool	operator> (const QDate &other) const

bool	operator>= (const KLocalizedDate &other) const

bool	operator>= (const QDate &other) const

void	setCalendarSystem (KLocale::CalendarSystem calendarSystem)

bool	setCurrentDate ()

bool	setDate (const QDate &date)

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

bool	setDate (int year, int dayOfYear)

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

bool	setDate (KLocale::WeekNumberSystem weekNumberSystem, int year, int weekOfYear, int dayOfWeek)

int	toJulianDay () const

int	week (int *yearNum=0) const

int	week (KLocale::WeekNumberSystem weekNumberSystem, int *yearNum=0) const

int	weeksInYear () const

int	weeksInYear (KLocale::WeekNumberSystem weekNumberSystem) const

int	year () const

int	yearInEra () const

int	yearsDifference (const KLocalizedDate &toDate) const

int	yearsDifference (const QDate &toDate) const

Static Public Member Functions
static KLocalizedDate	currentDate ()

static KLocalizedDate	fromDate (const QDate &date)

static KLocalizedDate	fromJulianDay (int jd)

static KLocalizedDate	readDate (const QString &dateString, KLocale::DateTimeParseMode parseMode=KLocale::LiberalParsing, const KCalendarSystem *calendar=0)

static KLocalizedDate	readDate (const QString &dateString, KLocale::ReadDateFlags formatFlags, KLocale::DateTimeParseMode parseMode=KLocale::LiberalParsing, const KCalendarSystem *calendar=0)

static KLocalizedDate	readDate (const QString &dateString, const QString &dateFormat, KLocale::DateTimeParseMode parseMode=KLocale::LiberalParsing, KLocale::DateTimeFormatStandard formatStandard=KLocale::KdeFormat, const KCalendarSystem *calendar=0)

Friends
QDataStream &	operator<< (QDataStream &out, const KLocalizedDate &date)

QDebug	operator<< (QDebug, const KLocalizedDate &)

QDataStream &	operator>> (QDataStream &in, KLocalizedDate &date)

Detailed Description

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

Topics:

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.

Definition at line 138 of file klocalizeddate.h.

Constructor & Destructor Documentation

KLocalizedDate::KLocalizedDate	(	const QDate &	date = `QDate()`,
		const KCalendarSystem *	calendar = `0`
	)

explicit

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 Default and Custom Locale and Calendar System 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

Definition at line 93 of file klocalizeddate.cpp.

KLocalizedDate::KLocalizedDate	(	int	year,
		int	month,
		int	day,
		const 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 Default and Custom Locale and Calendar System 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

Definition at line 98 of file klocalizeddate.cpp.

KLocalizedDate::KLocalizedDate ( const KLocalizedDate & rhs )

Copy constructor.

Parameters

rhs	the date to copy

Definition at line 104 of file klocalizeddate.cpp.

KLocalizedDate::~KLocalizedDate ( )

Destructor.

Definition at line 121 of file klocalizeddate.cpp.

Member Function Documentation

KLocalizedDate KLocalizedDate::addDays ( int days ) const

Returns a KLocalizedDate containing a date days days later.

See also: addDaysTo(); addYears() addMonths(); dateDifference() yearsDifference()

Parameters

days	number of days to add

Returns: The new date, null date if any errors

Definition at line 441 of file klocalizeddate.cpp.

bool KLocalizedDate::addDaysTo ( 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(); addYearsTo(), addMonthsTo(); dateDifference() yearsDifference()

Parameters

days	The number of days to add

Returns: if the resulting date is valid

Definition at line 448 of file klocalizeddate.cpp.

KLocalizedDate KLocalizedDate::addMonths ( int months ) const

Returns a KLocalizedDate containing a date months months later.

See also: addMonthsTo(); addYears() addDays(); dateDifference() yearsDifference()

Parameters

months number of months to add

Returns: The new date, null date if any errors

Definition at line 428 of file klocalizeddate.cpp.

bool KLocalizedDate::addMonthsTo ( 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(); addYearsTo() addDaysTo(); dateDifference() yearsDifference()

Parameters

months The number of months to add

Returns: if the resulting date is valid

Definition at line 435 of file klocalizeddate.cpp.

KLocalizedDate KLocalizedDate::addYears ( int years ) const

Returns a KLocalizedDate containing a date years years later.

See also: addYearsTo(); addMonths() addDays(); dateDifference() yearsDifference()

Parameters

years The number of years to add

Returns: The new date, null date if any errors

Definition at line 414 of file klocalizeddate.cpp.

bool KLocalizedDate::addYearsTo ( 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(); addMonthsTo() addDaysTo(); dateDifference() yearsDifference()

Parameters

years The number of years to add

Returns: if the resulting date is valid

Definition at line 422 of file klocalizeddate.cpp.

const KCalendarSystem * KLocalizedDate::calendar ( ) const

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; calendarSystem; setCalendarSystem

Returns: the current calendar system instance

Definition at line 149 of file klocalizeddate.cpp.

KLocale::CalendarSystem KLocalizedDate::calendarSystem ( )

Returns the Calendar System used by this localized date instance.

See also: KLocale::CalendarSystem; setCalendarSystem()

Returns: the Calendar System currently used

Definition at line 144 of file klocalizeddate.cpp.

KLocalizedDate KLocalizedDate::currentDate ( )

static

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

See also: setCurrentDate()

Returns: today's localized date

Definition at line 222 of file klocalizeddate.cpp.

QDate KLocalizedDate::date ( ) const

Returns the currently set date as a QDate.

Returns: the currently set date as a QDate

Definition at line 248 of file klocalizeddate.cpp.

void KLocalizedDate::dateDifference	(	const KLocalizedDate &	toDate,
		int *	yearsDiff,
		int *	monthsDiff,
		int *	daysDiff,
		int *	direction
	)		const

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(); 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

Definition at line 454 of file klocalizeddate.cpp.

void KLocalizedDate::dateDifference	(	const QDate &	toDate,
		int *	yearsDiff,
		int *	monthsDiff,
		int *	daysDiff,
		int *	direction
	)		const

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(); 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

Definition at line 460 of file klocalizeddate.cpp.

int KLocalizedDate::day ( ) const

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

See Date Formatting for why you should never display this value.

See also: formatDate()

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

Definition at line 268 of file klocalizeddate.cpp.

int KLocalizedDate::dayOfWeek ( ) const

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 Date Formatting for why you should never display this value.

See also: formatDate()

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

Definition at line 293 of file klocalizeddate.cpp.

int KLocalizedDate::dayOfYear ( ) const

Returns the day number of year for the date.

The days are numbered 1..daysInYear()

See Date Formatting for why you should never display this value.

See also: formatDate()

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

Definition at line 288 of file klocalizeddate.cpp.

int KLocalizedDate::daysDifference ( const KLocalizedDate & toDate ) const

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

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

Parameters

toDate The date to end at

Returns: The number of days difference

Definition at line 486 of file klocalizeddate.cpp.

int KLocalizedDate::daysDifference ( const QDate & toDate ) const

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

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

Parameters

toDate The date to end at

Returns: The number of days difference

Definition at line 491 of file klocalizeddate.cpp.

int KLocalizedDate::daysInMonth ( ) const

Returns the number of days in the month.

See Date Formatting for why you should never display this value.

See also: formatDate()

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

Definition at line 328 of file klocalizeddate.cpp.

int KLocalizedDate::daysInWeek ( ) const

Returns the number of days in the week.

See Date Formatting for why you should never display this value.

See also: formatDate()

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

Definition at line 333 of file klocalizeddate.cpp.

int KLocalizedDate::daysInYear ( ) const

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 Date Formatting for why you should never display this value.

See also: formatDate()

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

Definition at line 323 of file klocalizeddate.cpp.

QString KLocalizedDate::eraName ( ) const

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 Date Formatting for more details on Date Formatting.

See also: formatDate()

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

Definition at line 273 of file klocalizeddate.cpp.

QString KLocalizedDate::eraYear ( ) const

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

See Date Formatting for more details on Date Formatting.

See also: formatDate()

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

Definition at line 278 of file klocalizeddate.cpp.

KLocalizedDate KLocalizedDate::firstDayOfMonth ( ) const

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

See also: lastDayOfMonth()

Returns: The first day of the month

Definition at line 510 of file klocalizeddate.cpp.

KLocalizedDate KLocalizedDate::firstDayOfYear ( ) const

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

See also: lastDayOfYear()

Returns: The first day of the year

Definition at line 496 of file klocalizeddate.cpp.

QString KLocalizedDate::formatDate ( KLocale::DateFormat dateFormat = KLocale::LongDate ) const

Returns the Date as a localized string in the requested standard Locale format.

See Date Formatting for more details on Date Formatting and valid Locale formats.

See also: formatDate()

Parameters

dateFormat the standard date format to use

Returns: The date as a localized string

Definition at line 349 of file klocalizeddate.cpp.

QString KLocalizedDate::formatDate	(	const QString &	formatString,
		KLocale::DateTimeFormatStandard	formatStandard = `KLocale::KdeFormat`
	)		const

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

See Date Formatting for more details on Date Formatting and valid format codes.

Please use with care and only in situations where the standard Locale formats or the component format methods do not provide what you need. You should almost always translate your formatString as documented above. Using the standard DateFormat options instead would take care of the translation for you.

The toFormat parameter is a good candidate to be made translatable, so that translators can adapt it to their language's convention. There should also be a context using the "kdedt-format" keyword (for automatic validation of translations) and stating the format's purpose:

QDate reportDate;
KGlobal::locale()->calendar()->setDate(reportDate, reportYear, reportMonth, 1);
dateFormat = i18nc("(kdedt-format) Report month and year in report header", "%B %Y"));
dateString = KGlobal::locale()->calendar()->formatDate(reportDate, dateFormat);

The date format string can be defined using either the KDE, POSIX or the Qt subset of the UNICODE standards.

The KDE standard closely follows the POSIX standard but with some exceptions. Always use the KDE standard within KDE, but where interaction is required with external POSIX compliant systems (e.g. Gnome, glibc, etc) the POSIX standard should be used. The UNICODE standard is provided for comaptability with QDate and so is not yet the full standard, only what Qt currently supports.

Date format strings are made up of date components and string literals. Date components are prefixed by a % escape character and are made up of optional padding and case modifier flags, an optional width value, and a compulsary code for the actual date component: %[Flags][Width][Componant] e.g. _^5Y No spaces are allowed.

The Flags can modify the padding character and/or case of the Date Componant. The Flags are optional and may be combined and/or repeated in any order, in which case the last Padding Flag and last Case Flag will be the ones used. The Flags must be immediately after the % and before any Width.

The Width can modify how wide the date Componant is padded to. The Width is an optional interger value and must be after any Flags but before the Componant. If the Width is less than the minimum defined for a Componant then the default minimum will be used instead.

By default most numeric Date Componants are right-aligned with leading 0's.

By default all string name fields are capital case and unpadded.

The following Flags may be specified:

- (hyphen) no padding (e.g. 1 Jan and "%-j" = "1")
_ (underscore) pad with spaces (e.g. 1 Jan and "%-j" = " 1")
0 (zero) pad with 0's (e.g. 1 Jan and "%0j" = "001")
^ (caret) make uppercase (e.g. 1 Jan and "%^B" = "JANUARY")
# (hash) invert case (e.g. 1 Jan and "%#B" = "???")

The following Date Componants can be specified:

Y the year to 4 digits (e.g. "1984" for 1984, "0584" for 584, "0084" for 84)
C the 'century' portion of the year to 2 digits (e.g. "19" for 1984, "05" for 584, "00" for 84)
y the lower 2 digits of the year to 2 digits (e.g. "84" for 1984, "05" for 2005)
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 2 digits (January="01", December="12")
n the month number to 1 digit (January="1", December="12"), see notes!
d the day number of the month to 2 digits (e.g. "01" on the first of March)
e the day number of the month to 1 digit (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 3 digits (e.g. "001" for 1 Jan)
V the ISO week of the year number to 2 digits (e.g. "01" for ISO Week 1)
G the year number in long form of the ISO week of the year to 4 digits (e.g. "2004" for 1 Jan 2005)
g the year number in short form of the ISO week of the year to 2 digits (e.g. "04" for 1 Jan 2005)
u the day of the week number to 1 digit (e.g. "1" for Monday)
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

Everything else in the format string will be taken as literal text.

Examples: "%Y-%m-%d" = "2009-01-01" "%Y-%-m-%_4d" = "2009-1- 1"

The following format codes behave differently in the KDE and POSIX standards

e in GNU/POSIX is space padded to 2 digits, in KDE is not padded
n in GNU/POSIX is newline, in KDE is short month number

The following POSIX format codes are currently not supported:

U US week number
w US day of week
W US week number
O locale's alternative numeric symbols, in KDE is not supported

%0 is not supported as the returned result is always in the locale's chosen numeric symbol digit set.

See also: formatDate()

Parameters

formatString	the date format to use
formatStandard	the standard the `dateFormat` uses, defaults to KDE Standard

Returns: The date as a localized string

Definition at line 354 of file klocalizeddate.cpp.

QString KLocalizedDate::formatDate	(	KLocale::DateTimeComponent	component,
		KLocale::DateTimeComponentFormat	format = `KLocale::DefaultComponentFormat`,
		KLocale::WeekNumberSystem	weekNumberSystem = `KLocale::DefaultWeekNumber`
	)		const

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

See Date 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

Definition at line 359 of file klocalizeddate.cpp.

KLocalizedDate KLocalizedDate::fromDate ( const QDate & date )

static

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

Definition at line 227 of file klocalizeddate.cpp.

KLocalizedDate KLocalizedDate::fromJulianDay ( int jd )

static

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

Definition at line 232 of file klocalizeddate.cpp.

void KLocalizedDate::getDate	(	int *	year,
		int *	month,
		int *	day
	)		const

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

See Date Formatting for why you should never display this value.

See also: setDate(); formatDate()

Parameters

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

Definition at line 253 of file klocalizeddate.cpp.

bool KLocalizedDate::isLeapYear ( ) const

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

Definition at line 338 of file klocalizeddate.cpp.

bool KLocalizedDate::isNull ( ) const

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

Definition at line 163 of file klocalizeddate.cpp.

bool KLocalizedDate::isValid ( ) const

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

See also: isNull

Returns: true if the date is valid, false otherwise

Definition at line 168 of file klocalizeddate.cpp.

KLocalizedDate KLocalizedDate::lastDayOfMonth ( ) const

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

See also: firstDayOfMonth()

Returns: The last day of the month

Definition at line 517 of file klocalizeddate.cpp.

KLocalizedDate KLocalizedDate::lastDayOfYear ( ) const

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

See also: firstDayOfYear()

Returns: The last day of the year

Definition at line 503 of file klocalizeddate.cpp.

int KLocalizedDate::month ( ) const

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

See Date Formatting for why you should never display this value.

See also: formatDate()

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

Definition at line 263 of file klocalizeddate.cpp.

int KLocalizedDate::monthsDifference ( const KLocalizedDate & toDate ) const

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(); dateDifference() yearsDifference() daysDifference()

Parameters

toDate The date to end at

Returns: The number of months difference

Definition at line 476 of file klocalizeddate.cpp.

int KLocalizedDate::monthsDifference ( const QDate & toDate ) const

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(); dateDifference() yearsDifference() daysDifference()

Parameters

toDate The date to end at

Returns: The number of months difference

Definition at line 481 of file klocalizeddate.cpp.

int KLocalizedDate::monthsInYear ( ) const

Returns number of months in the year.

See Date Formatting for why you should never display this value.

See also: formatDate()

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

Definition at line 308 of file klocalizeddate.cpp.

bool KLocalizedDate::operator!= ( const KLocalizedDate & other ) const

KLocalizedDate inequality operator.

Parameters

other the date to compare

Definition at line 540 of file klocalizeddate.cpp.

bool KLocalizedDate::operator!= ( const QDate & other ) const

QDate inequality operator.

Parameters

other the date to compare

Definition at line 545 of file klocalizeddate.cpp.

bool KLocalizedDate::operator< ( const KLocalizedDate & other ) const

KLocalizedDate less than operator.

Parameters

other the date to compare

Definition at line 550 of file klocalizeddate.cpp.

bool KLocalizedDate::operator< ( const QDate & other ) const

QDate less than operator.

Parameters

other the date to compare

Definition at line 555 of file klocalizeddate.cpp.

bool KLocalizedDate::operator<= ( const KLocalizedDate & other ) const

KLocalizedDate less than or equal to operator.

Parameters

other the date to compare

Definition at line 560 of file klocalizeddate.cpp.

bool KLocalizedDate::operator<= ( const QDate & other ) const

QDate less than or equal to operator.

Parameters

other the date to compare

Definition at line 565 of file klocalizeddate.cpp.

KLocalizedDate & KLocalizedDate::operator= ( const KLocalizedDate & rhs )

Assignment operator.

Parameters

rhs	the date to assign

Definition at line 109 of file klocalizeddate.cpp.

KLocalizedDate & KLocalizedDate::operator= ( const QDate & rhs )

Assignment operator.

Parameters

rhs	the date to assign

Definition at line 115 of file klocalizeddate.cpp.

bool KLocalizedDate::operator== ( const KLocalizedDate & other ) const

KLocalizedDate equality operator.

Parameters

other the date to compare

Definition at line 530 of file klocalizeddate.cpp.

bool KLocalizedDate::operator== ( const QDate & other ) const

QDate equality operator.

Parameters

other the date to compare

Definition at line 535 of file klocalizeddate.cpp.

bool KLocalizedDate::operator> ( const KLocalizedDate & other ) const

KLocalizedDate greater than operator.

Parameters

other the date to compare

Definition at line 570 of file klocalizeddate.cpp.

bool KLocalizedDate::operator> ( const QDate & other ) const

QDate greater than operator.

Parameters

other the date to compare

Definition at line 575 of file klocalizeddate.cpp.

bool KLocalizedDate::operator>= ( const KLocalizedDate & other ) const

KLocalizedDate greater than or equal to operator.

Parameters

other the date to compare

Definition at line 580 of file klocalizeddate.cpp.

bool KLocalizedDate::operator>= ( const QDate & other ) const

QDate greater than or equal to operator.

Parameters

other the date to compare

Definition at line 585 of file klocalizeddate.cpp.

KLocalizedDate KLocalizedDate::readDate	(	const QString &	dateString,
		KLocale::DateTimeParseMode	parseMode = `KLocale::LiberalParsing`,
		const KCalendarSystem *	calendar = `0`
	)

static

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

See Date Parsing for more details on Date Parsing from strings.

This method is more liberal and will return a valid date if the dateString matches any of the KLocale::ReadDateFlags formats for the Locale.

If you require a certain KLocale::ReadDateFlags format or a customized format string, use one of the other readDate() methods.

Parameters

dateString	the string to parse
parseMode	how strictly to apply the locale formats to the `dateString`
calendar	the Calendar System to use when parsing the date

Returns: the localized date parsed from the string

Definition at line 372 of file klocalizeddate.cpp.

KLocalizedDate KLocalizedDate::readDate	(	const QString &	dateString,
		KLocale::ReadDateFlags	formatFlags,
		KLocale::DateTimeParseMode	parseMode = `KLocale::LiberalParsing`,
		const KCalendarSystem *	calendar = `0`
	)

static

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

See Date Parsing for more details on Date Parsing from strings.

This method is stricter and will return a valid date only if the dateString matches one of the dateFlags formats requested.

If you require any KLocale::ReadDateFlags format or a customized format string, use one of the other readDate() methods.

Parameters

dateString	the string to parse
formatFlags	the locale format(s) to try parse the string with
parseMode	how strictly to apply the `formatFlags` to the `dateString`
calendar	the Calendar System to use when parsing the date

Returns: the localized date parsed from the string

Definition at line 383 of file klocalizeddate.cpp.

KLocalizedDate KLocalizedDate::readDate	(	const QString &	dateString,
		const QString &	dateFormat,
		KLocale::DateTimeParseMode	parseMode = `KLocale::LiberalParsing`,
		KLocale::DateTimeFormatStandard	formatStandard = `KLocale::KdeFormat`,
		const KCalendarSystem *	calendar = `0`
	)

static

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

See Date 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

Definition at line 395 of file klocalizeddate.cpp.

void KLocalizedDate::setCalendarSystem ( 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 Default and Custom Locale and Calendar System for more details on using custom Calendar Systems.

See also: KLocale::CalendarSystem; calendarSystem()

Parameters

calendarSystem the Calendar System to use

Definition at line 131 of file klocalizeddate.cpp.

bool KLocalizedDate::setCurrentDate ( )

Set the date to today's date.

See also: currentDate()

Returns: true if the date is valid, false otherwise

Definition at line 210 of file klocalizeddate.cpp.

bool KLocalizedDate::setDate ( const QDate & date )

Set the date using a QDate.

Parameters

date	the QDate to set to

Returns: true if the date is valid, false otherwise

Definition at line 179 of file klocalizeddate.cpp.

bool KLocalizedDate::setDate	(	int	year,
		int	month,
		int	day
	)

Set the date's year, month and day.

The range of the year, month and day, and the validity of the date as a whole depends on which Calendar System is being used.

See also: getDate()

Parameters

year	year number
month	month of year number
day	day of month

Returns: true if the date is valid, false otherwise

Definition at line 185 of file klocalizeddate.cpp.

bool KLocalizedDate::setDate	(	int	year,
		int	dayOfYear
	)

Set the date using the year number and day of year number only.

See also: dayOfYear()

Parameters

year	year
dayOfYear	day of year

Returns: true if the date is valid, false otherwise

Definition at line 191 of file klocalizeddate.cpp.

bool KLocalizedDate::setDate	(	QString	eraName,
		int	yearInEra,
		int	month,
		int	day
	)

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

See also: eraName(); yearInEra()

Parameters

eraName	Era string
yearInEra	Year In Era number
month	Month number
day	Day Of Month number

Returns: true if the date is valid, false otherwise

Definition at line 197 of file klocalizeddate.cpp.

bool KLocalizedDate::setDate	(	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(); 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

Definition at line 203 of file klocalizeddate.cpp.

int KLocalizedDate::toJulianDay ( ) const

Returns the currently set date as a Julian Day number.

See also: fromJulianDay()

Returns: the currently set date as a Julian Day number

Definition at line 243 of file klocalizeddate.cpp.

int KLocalizedDate::week ( int * yearNum = 0 ) const

Returns the localized Week Number for the date.

See Date Formatting for why you should never display this value.

This may be ISO, US, or any other supported week numbering scheme. If you specifically require the ISO Week or any other scheme, you should use the week(KLocale::WeekNumberSystem) form.

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.

See also: weeksInYear(); formatDate()

Parameters

yearNum returns the year the date belongs to

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

Definition at line 298 of file klocalizeddate.cpp.

int KLocalizedDate::week	(	KLocale::WeekNumberSystem	weekNumberSystem,
		int *	yearNum = `0`
	)		const

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

See Date 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(); 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

Definition at line 303 of file klocalizeddate.cpp.

int KLocalizedDate::weeksInYear ( ) const

Returns the number of localized weeks in the currently set year.

See Date Formatting for why you should never display this value.

If you specifically require the number of ISO Weeks, you should use weeksInYear(KLocale::IsoWeekNumber)

See also: week(); formatDate()

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

Definition at line 313 of file klocalizeddate.cpp.

int KLocalizedDate::weeksInYear ( KLocale::WeekNumberSystem weekNumberSystem ) const

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

See Date 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(); formatDate()

Parameters

weekNumberSystem the week number system to use

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

Definition at line 318 of file klocalizeddate.cpp.

int KLocalizedDate::year ( ) const

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

See Date Formatting for why you should never display this value.

See also: formatDate()

Returns: the localized year number

Definition at line 258 of file klocalizeddate.cpp.

int KLocalizedDate::yearInEra ( ) const

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

See Date Formatting for why you should never display this value.

See also: formatDate(); formatYearInEra()

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

Definition at line 283 of file klocalizeddate.cpp.

int KLocalizedDate::yearsDifference ( const KLocalizedDate & toDate ) const

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(); dateDifference() monthsDifference() daysDifference()

Parameters

toDate The date to end at

Returns: The number of years difference

Definition at line 466 of file klocalizeddate.cpp.

int KLocalizedDate::yearsDifference ( const QDate & toDate ) const

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(); dateDifference() monthsDifference() daysDifference()

Parameters

toDate The date to end at

Returns: The number of years difference

Definition at line 471 of file klocalizeddate.cpp.

Friends And Related Function Documentation

QDataStream& operator<<	(	QDataStream &	out,
		const KLocalizedDate &	date
	)

friend

Data stream output operator.

Parameters

out	the datastream to write to
date	the date to write to the stream

Definition at line 590 of file klocalizeddate.cpp.

QDebug operator<<	(	QDebug	,
		const KLocalizedDate &
	)

friend

Debug stream output operator.

Parameters

debug	the debug datastream to write to
date	the date to write to the stream

Definition at line 605 of file klocalizeddate.cpp.

QDataStream& operator>>	(	QDataStream &	in,
		KLocalizedDate &	date
	)

friend

Data stream input operator.

Parameters

in	the datastream to read from
date	the date to read from the stream

Definition at line 595 of file klocalizeddate.cpp.

The documentation for this class was generated from the following files:

KDECore

Public Member Functions

Static Public Member Functions

Friends

Detailed Description

Introduction

Calendar System

Default and Custom Locale and Calendar System

Date Formatting

Date Parsing

Date Maths

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation

KDECore

kdelibs API Reference

Search