KLocalizedDate

#include <klocalizeddate.h>

Public Member Functions

 KLocalizedDate (const QDate &date=QDate(), const KCalendarSystem *calendar=nullptr)
 
 KLocalizedDate (int year, int month, int day, const KCalendarSystem *calendar=nullptr)
 
 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 KCalendarSystemcalendar () 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
 
KLocalizedDateoperator= (const KLocalizedDate &rhs)
 
KLocalizedDateoperator= (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=nullptr) const
 
int week (KLocale::WeekNumberSystem weekNumberSystem, int *yearNum=nullptr) 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=nullptr)
 
static KLocalizedDate readDate (const QString &dateString, KLocale::ReadDateFlags formatFlags, KLocale::DateTimeParseMode parseMode=KLocale::LiberalParsing, const KCalendarSystem *calendar=nullptr)
 
static KLocalizedDate readDate (const QString &dateString, const QString &dateFormat, KLocale::DateTimeParseMode parseMode=KLocale::LiberalParsing, KLocale::DateTimeFormatStandard formatStandard=KLocale::KdeFormat, const KCalendarSystem *calendar=nullptr)
 

Friends

QDataStreamoperator<< (QDataStream &out, const KLocalizedDate &date)
 
QDebug operator<< (QDebug, const KLocalizedDate &)
 
QDataStreamoperator>> (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");
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 137 of file klocalizeddate.h.

Constructor & Destructor Documentation

KLocalizedDate::KLocalizedDate ( const QDate date = QDate(),
const KCalendarSystem calendar = nullptr 
)
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
datethe QDate to set the KLocalizedDate to, defaults to invalid date
calendarthe calendar system to use, defaults to the global

Definition at line 95 of file klocalizeddate.cpp.

KLocalizedDate::KLocalizedDate ( int  year,
int  month,
int  day,
const KCalendarSystem calendar = nullptr 
)

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
yearthe year to set the KLocalizedDate to
monththe month to set the KLocalizedDate to
daythe day to set the KLocalizedDate to
calendarthe calendar system to use, defaults to the global

Definition at line 100 of file klocalizeddate.cpp.

KLocalizedDate::KLocalizedDate ( const KLocalizedDate rhs)

Copy constructor.

Parameters
rhsthe date to copy

Definition at line 106 of file klocalizeddate.cpp.

KLocalizedDate::~KLocalizedDate ( )

Destructor.

Definition at line 123 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
daysnumber of days to add
Returns
The new date, null date if any errors

Definition at line 443 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
daysThe number of days to add
Returns
if the resulting date is valid

Definition at line 450 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
monthsnumber of months to add
Returns
The new date, null date if any errors

Definition at line 430 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
monthsThe number of months to add
Returns
if the resulting date is valid

Definition at line 437 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
yearsThe number of years to add
Returns
The new date, null date if any errors

Definition at line 416 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
yearsThe number of years to add
Returns
if the resulting date is valid

Definition at line 424 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 151 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 146 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 224 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 250 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
toDateThe date to end at
yearsDiffReturns number of years difference
monthsDiffReturns number of months difference
daysDiffReturns number of days difference
directionReturns direction of difference, 1 if this Date <= toDate, -1 otherwise

Definition at line 456 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
toDateThe date to end at
yearsDiffReturns number of years difference
monthsDiffReturns number of months difference
daysDiffReturns number of days difference
directionReturns direction of difference, 1 if this Date <= toDate, -1 otherwise

Definition at line 462 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 270 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 295 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 290 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
toDateThe date to end at
Returns
The number of days difference

Definition at line 488 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
toDateThe date to end at
Returns
The number of days difference

Definition at line 493 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 330 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 335 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 325 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 275 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 280 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 512 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 498 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
dateFormatthe standard date format to use
Returns
The date as a localized string

Definition at line 351 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;
KLocale::global()->calendar()->setDate(reportDate, reportYear, reportMonth, 1);
dateFormat = i18nc("(kdedt-format) Report month and year in report header", "%B %Y"));
dateString = KLocale::global()->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
formatStringthe date format to use
formatStandardthe standard the dateFormat uses, defaults to KDE Standard
Returns
The date as a localized string

Definition at line 356 of file klocalizeddate.cpp.

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
componentThe date component to return
formatThe format to return the component in
weekNumberSystemTo override the default Week Number System to use
Returns
The string form of the date component

Definition at line 361 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
datethe date to set to
Returns
a localized date

Definition at line 229 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
jdthe Julian Day number to set to
Returns
a localized date

Definition at line 234 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
yearyear number returned in this variable
monthmonth number returned in this variable
dayday of month returned in this variable

Definition at line 255 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 340 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 165 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 170 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 519 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 505 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 265 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
toDateThe date to end at
Returns
The number of months difference

Definition at line 478 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
toDateThe date to end at
Returns
The number of months difference

Definition at line 483 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 310 of file klocalizeddate.cpp.

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

KLocalizedDate inequality operator.

Parameters
otherthe date to compare

Definition at line 542 of file klocalizeddate.cpp.

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

QDate inequality operator.

Parameters
otherthe date to compare

Definition at line 547 of file klocalizeddate.cpp.

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

KLocalizedDate less than operator.

Parameters
otherthe date to compare

Definition at line 552 of file klocalizeddate.cpp.

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

QDate less than operator.

Parameters
otherthe date to compare

Definition at line 557 of file klocalizeddate.cpp.

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

KLocalizedDate less than or equal to operator.

Parameters
otherthe date to compare

Definition at line 562 of file klocalizeddate.cpp.

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

QDate less than or equal to operator.

Parameters
otherthe date to compare

Definition at line 567 of file klocalizeddate.cpp.

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

Assignment operator.

Parameters
rhsthe date to assign

Definition at line 111 of file klocalizeddate.cpp.

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

Assignment operator.

Parameters
rhsthe date to assign

Definition at line 117 of file klocalizeddate.cpp.

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

KLocalizedDate equality operator.

Parameters
otherthe date to compare

Definition at line 532 of file klocalizeddate.cpp.

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

QDate equality operator.

Parameters
otherthe date to compare

Definition at line 537 of file klocalizeddate.cpp.

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

KLocalizedDate greater than operator.

Parameters
otherthe date to compare

Definition at line 572 of file klocalizeddate.cpp.

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

QDate greater than operator.

Parameters
otherthe date to compare

Definition at line 577 of file klocalizeddate.cpp.

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

KLocalizedDate greater than or equal to operator.

Parameters
otherthe date to compare

Definition at line 582 of file klocalizeddate.cpp.

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

QDate greater than or equal to operator.

Parameters
otherthe date to compare

Definition at line 587 of file klocalizeddate.cpp.

KLocalizedDate KLocalizedDate::readDate ( const QString dateString,
KLocale::DateTimeParseMode  parseMode = KLocale::LiberalParsing,
const KCalendarSystem calendar = nullptr 
)
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
dateStringthe string to parse
parseModehow strictly to apply the locale formats to the dateString
calendarthe Calendar System to use when parsing the date
Returns
the localized date parsed from the string

Definition at line 374 of file klocalizeddate.cpp.

KLocalizedDate KLocalizedDate::readDate ( const QString dateString,
KLocale::ReadDateFlags  formatFlags,
KLocale::DateTimeParseMode  parseMode = KLocale::LiberalParsing,
const KCalendarSystem calendar = nullptr 
)
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
dateStringthe string to parse
formatFlagsthe locale format(s) to try parse the string with
parseModehow strictly to apply the formatFlags to the dateString
calendarthe Calendar System to use when parsing the date
Returns
the localized date parsed from the string

Definition at line 385 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 = nullptr 
)
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
dateStringthe string to parse
dateFormatthe date format to try parse the string with
parseModehow strictly to apply the dateFormat to the dateString
formatStandardthe standard the dateFormat format uses
calendarthe Calendar System to use when parsing the date
Returns
the localized date parsed from the string

Definition at line 397 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
calendarSystemthe Calendar System to use

Definition at line 133 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 212 of file klocalizeddate.cpp.

bool KLocalizedDate::setDate ( const QDate date)

Set the date using a QDate.

Parameters
datethe QDate to set to
Returns
true if the date is valid, false otherwise

Definition at line 181 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
yearyear number
monthmonth of year number
dayday of month
Returns
true if the date is valid, false otherwise

Definition at line 187 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
yearyear
dayOfYearday of year
Returns
true if the date is valid, false otherwise

Definition at line 193 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
eraNameEra string
yearInEraYear In Era number
monthMonth number
dayDay Of Month number
Returns
true if the date is valid, false otherwise

Definition at line 199 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
weekNumberSystemthe week number system to use
yearyear
weekOfYearweek of year
dayOfWeekday of week Mon..Sun (1..7)
Returns
true if the date is valid, false otherwise

Definition at line 205 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 245 of file klocalizeddate.cpp.

int KLocalizedDate::week ( int *  yearNum = nullptr) 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
yearNumreturns the year the date belongs to
Returns
localized week number, -1 if input date invalid

Definition at line 300 of file klocalizeddate.cpp.

int KLocalizedDate::week ( KLocale::WeekNumberSystem  weekNumberSystem,
int *  yearNum = nullptr 
) 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
weekNumberSystemthe Week Number System to use
yearNumreturns the year the date belongs to
Returns
week number, -1 if input date invalid

Definition at line 305 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 315 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
weekNumberSystemthe week number system to use
Returns
number of weeks in the year, -1 if date invalid

Definition at line 320 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 260 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 285 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
toDateThe date to end at
Returns
The number of years difference

Definition at line 468 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
toDateThe date to end at
Returns
The number of years difference

Definition at line 473 of file klocalizeddate.cpp.

Friends And Related Function Documentation

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

Data stream output operator.

Parameters
outthe datastream to write to
datethe date to write to the stream

Definition at line 592 of file klocalizeddate.cpp.

QDebug operator<< ( QDebug  ,
const KLocalizedDate  
)
friend

Debug stream output operator.

Parameters
debugthe debug datastream to write to
datethe date to write to the stream

Definition at line 607 of file klocalizeddate.cpp.

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

Data stream input operator.

Parameters
inthe datastream to read from
datethe date to read from the stream

Definition at line 597 of file klocalizeddate.cpp.


The documentation for this class was generated from the following files:
This file is part of the KDE documentation.
Documentation copyright © 1996-2020 The KDE developers.
Generated on Wed Jul 1 2020 22:56:50 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.