CopperSpice API  1.9.1
QDate Class Reference

Stores a calendar date which consists of a month, day, and year. More...

Public Types

enum  MonthNameType
 

Public Methods

constexpr QDate ()
 
 QDate (int y, int m, int d)
 
QDate addDays (qint64 days) const
 
QDate addDuration (std::chrono::days days) const
 
QDate addMonths (qint64 months) const
 
QDate addYears (qint64 years) const
 
int day () const
 
int dayOfWeek () const
 
int dayOfYear () const
 
int daysInMonth () const
 
int daysInYear () const
 
qint64 daysTo (const QDate &value) const
 
QDateTime endOfDay (const QTimeZone &zone=default_tz ()) const
 
void getDate (int *year, int *month, int *day) const
 
bool isNull () const
 
bool isValid () const
 
int month () const
 
bool operator!= (const QDate &other) const
 
bool operator< (const QDate &other) const
 
bool operator<= (const QDate &other) const
 
bool operator== (const QDate &other) const
 
bool operator> (const QDate &other) const
 
bool operator>= (const QDate &other) const
 
bool setDate (int year, int month, int day)
 
QDateTime startOfDay (const QTimeZone &zone=default_tz ()) const
 
constexpr qint64 toJulianDay () const
 
std::chrono::sys_days toStdSysDays () const
 
QString toString (const QString &format) const
 
QString toString (Qt::DateFormat format=Qt::TextDate) const
 
int weekNumber (int *yearNumber=nullptr) const
 
int year () const
 

Static Public Methods

static QDate currentDate ()
 
static constexpr QDate fromJulianDay (qint64 dayNumber)
 
static QDate fromStdSysDays (const std::chrono::sys_days &days)
 
static QDate fromString (const QString &str, const QString &format)
 
static QDate fromString (const QString &str, Qt::DateFormat format=Qt::TextDate)
 
static bool isLeapYear (int year)
 
static bool isValid (int year, int month, int day)
 
static QString longDayName (int weekday, MonthNameType type=DateFormat)
 
static QString longMonthName (int month, MonthNameType type=DateFormat)
 
static QString shortDayName (int weekday, MonthNameType type=DateFormat)
 
static QString shortMonthName (int month, MonthNameType type=DateFormat)
 

Friends

QDataStreamoperator<< (QDataStream &stream, const QDate &date)
 
QDataStreamoperator>> (QDataStream &stream, QDate &date)
 
class QDateTime
 

Detailed Description

The QDate class stores a calendar date which consists of a month, day, and year. The Julian calendar is used for any date prior to October 15 1582. The Gregorian calendar is used for dates after 15 October 1582. This class retrieves the current date from the operating system's internal clock. Many of the methods in this class are used to calculate a new date based on some offset or to compare two existing dates.

A QDate is typically created by specifying the year, month, and day. If the year is two digits it will be interpreted as the years 0 through 99. A date can also be constructed with the static method currentDate() which creates a QDate containing the system clock date.

The month(), day(), and year() methods provide access to the integer values for the day, month, and year numbers. Other methods of interest include dayOfWeek() and dayOfYear(). There are a full set of operators to compare two QDate values where a smaller date means earlier and a larger date is later in time.

Gregorian and Julian Calendars

The switch from the Julian calendar to the Gregorian calendar happened between October 4 1582 to October 15 1582. This 10 day gap is part of Roman history and the actually skipped these days to adjust to the new calendar. Other regions of the world made the calendar transition at different times, although many areas moved within a year. Notable exceptions are the British Empire which changed over in 1752 and Greece which moved to the Gregorian calendar in 1923.

CopperSpice follows the common practice of using the calendar corresponding to the Roman locale. QDate uses the Julian calendar for dates prior to October 4 1582 and the Gregorian calendar starting on October 15 1582. All dates within the gap are invalid.

If you use QDateTime for a calendar date in this range, the day after 4 October 1582 will be 15 October 1582.

Year 0

There is no year 0 and attempting to construct a date for that year results in an invalid QDate.

The year -1 refers to the year "1 before Christ" or BCE which stands for "before common era". The day before January 1 0001 is December 31 0001 BCE. The notation CE stands for "common era" and refers to dates "after Christ".

Before Common Era

  • lifetime of Alexander the Great
  • construction of the Egyptian Pyramids
  • abacus invented in Sumer and Babylonia

Common Era

  • development of computer software
  • invention of the motorized vehicles
  • birthday of anyone reading this documentation

Range of Valid Dates

The QDate class is implemented using a qint64 which stores the number of days since November 24 4714 BCE in the Gregorian calendar. QDateTime is also implemented using a qint64 which stores the number of milliseconds since Jan 1 1970 at midnight UTC.

For most use cases QDate and QDateTime will store the same date value. You should use QDate to prevent an overflow when the calendar date might be extremely far in the past or the future.

See also
QCalendarWidget, QDateTime, QDateEdit, QDateTimeEdit, QTime

Member Enumeration Documentation

This enum describes the types of string representations used for the month name.

ConstantValueDescription
QDate::DateFormat 0 This type of name can be used for date-to-string formatting.
QDate::StandaloneFormat 1 This type is used when you need to enumerate months or weekdays. Usually standalone names are represented in singular forms with capitalized first letter.

Constructor & Destructor Documentation

constexpr QDate::QDate ( )
inlineconstexpr

Constructs an invalid QDate.

See also
isNull(), isValid()
QDate::QDate ( int  y,
int  m,
int  d 
)

Constructs a new QDate with year y, month m, and day d. If the specified date is invalid the QDate will be default constructed.

An example of an invalid date would be January 43 1950. Years 0 to 99 are interpreted as years in the first century.

See also
isValid()

Method Documentation

QDate QDate::addDays ( qint64  days) const
nodiscard

Adds the given number of days to the current QDate and returns the result. If days is negative the value for days is subtracted from this QDate.

See also
addMonths(), addYears(), daysTo()
QDate QDate::addDuration ( std::chrono::days  days) const
nodiscardinline

Adds the given number of days to the current QDate and returns the result. If days is negative the value for days is subtracted from this QDate.

Note
This method is only available if your compiler supports the C++20 features of std::chrono.
See also
addMonths(), addYears(), daysTo()
QDate QDate::addMonths ( qint64  months) const
nodiscard

Adds the given number of months to the current QDate and returns the result. If months is negative the value for months is subtracted from this QDate.

If the ending date does not exist in the resulting year, the date will be decremented to the latest valid date. There is an anomaly in the Gregorian calendar in the days October 5 1582 through October 14 1582. These days are missing and therefore do not exist. If this calculation ends in one of those days QDate will return either October 4 or October 15.

See also
addDays(), addYears()
QDate QDate::addYears ( qint64  years) const
nodiscard

Adds the given number of years to the current QDate and returns the result. If years is negative the value for years is subtracted from this QDate.

If the ending date does not exist in the resulting year, the date will be decremented to the latest valid date. For example, if the original date was Feb 29 and the new date is not a leap year, the date will be changed to Feb 28.

See also
addDays(), addMonths()
QDate QDate::currentDate ( )
static

Returns the current QDate as reported by the system clock.

See also
QTime::currentTime(), QDateTime::currentDateTime()
int QDate::day ( ) const

Returns the day of the month (1 to 31) for this QDate.

See also
dayOfWeek(), month(), year()
int QDate::dayOfWeek ( ) const

Returns the weekday (1 = Monday to 7 = Sunday) for this QDate.

See also
day(), dayOfYear(), Qt::DayOfWeek
int QDate::dayOfYear ( ) const

Returns the day of the year (1 to 365 or 366 on leap years) for this QDate.

See also
day(), dayOfWeek()
int QDate::daysInMonth ( ) const

Returns the number of days in the month (28 to 31) for this QDate.

See also
day(), daysInYear()
int QDate::daysInYear ( ) const

Returns the number of days in the year (365 or 366) for this QDate.

See also
day(), daysInMonth()
qint64 QDate::daysTo ( const QDate &  value) const

Returns the number of days between this QDate and the given value. This method will return a negative number if value is before this QDate.

QDate d1(2018, 5, 17);
QDate d2(2018, 5, 20);
d1.daysTo(d2); // returns 3
d2.daysTo(d1); // returns -3
See also
addDays()
QDateTime QDate::endOfDay ( const QTimeZone zone = default_tz()) const

Returns the last millisecond of the current QDate in the given zone. If no time zone is passed then the local time zone will be used.

See also
startOfDay()
constexpr QDate QDate::fromJulianDay ( qint64  dayNumber)
inlinestaticconstexpr

Converts the integer Julian day dayNumber to a QDate.

See also
toJulianDay()
QDate QDate::fromStdSysDays ( const std::chrono::sys_days &  days)
inlinestatic

Returns a QDate which is days after January 1, 1970. If days is negative then days will be subtracted from January 1, 1970.

Note
This method is only available if your compiler supports the C++20 features of std::chrono.
See also
toStdSysDays()
QDate QDate::fromString ( const QString str,
const QString format 
)
static

Returns the QDate represented by the str using the format given. If the string does not represent a valid date then QDate will set to an invalid date.

The following expressions can be used as part of the format. If any other characters are used in the format they will be treated as literal text. Any sequence of characters which are enclosed in single quotes will also be treated as literal text.

ExpressionOutput
d The day as a number without a leading zero (1 to 31)
dd The day as a number with a leading zero (01 to 31)
ddd The abbreviated localized day name (e.g. 'Mon' to 'Sun'). Uses QDate::shortDayName().
dddd The long localized day name (e.g. 'Monday' to 'Sunday'). Uses QDate::longDayName().
M The month as a number without a leading zero (1 to 12)
MM The month as a number with a leading zero (01 to 12)
MMM The abbreviated localized month name (e.g. 'Jan' to 'Dec'). Uses QDate::shortMonthName().
MMMM The long localized month name (e.g. 'January' to 'December'). Uses QDate::longMonthName().
yy The year as two digit number (00 to 99)
yyyy The year as four digit number. If the year is negative, a minus sign is prepended in addition.
QDate date = QDate::fromString("1MM12car2023", "d'MM'MMcaryyyy"); // 1 December 2023

The expressions which do not expect leading zeroes (d, M) will be greedy. This means they will use two digits even if this will put them outside the accepted range of values and leaves too few digits for other sections. For example, the following format string does not mean January 30 because the M will grab two digits, resulting in an invalid date.

QDate date = QDate::fromString("130", "Md"); // invalid date

For any field which is not represented in the format, the following defaults are used.

FieldDefault value
Year 1900
Month 1
Day 1

The following examples demonstrate default values.

QDate::fromString("1.30", "M.d"); // January 30 1900
QDate::fromString("20000110", "yyyyMMdd"); // January 10, 2000
QDate::fromString("20000110", "yyyyMd"); // January 10, 2000
See also
toString(), QDateTime::fromString(), QDateTime::toString(), QTime::fromString(), QTime::toString()
QDate QDate::fromString ( const QString str,
Qt::DateFormat  format = Qt::TextDate 
)
static

Returns the QDate represented by the str using the format given. If the string does not represent a valid date then QDate will be set to an invalid date.

If the format is Qt::TextDate then use the English short month names in the passed str. Localized month names can also be used depending on the user's locale settings.

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

Extracts this QDate and populates year, month, and day. Any variable which is a nullptr will not be populated with a value.

See also
day(), month(), year(), isValid()
bool QDate::isLeapYear ( int  year)
static

Returns true if the specified year is a leap year, otherwise returns false.

bool QDate::isNull ( ) const
inline

Returns true if the date is null, otherwise returns false.

See also
isValid()
bool QDate::isValid ( ) const
inline

Returns true if this QDate is valid, otherwise returns false.

See also
isNull()
bool QDate::isValid ( int  year,
int  month,
int  day 
)
static

Returns true if the specified year, month, and day are valid, otherwise returns false.

QDate::isValid(2022, 5, 17); // true
QDate::isValid(2022, 2, 30); // false (Feb 30 does not exist)
QDate::isValid(2024, 2, 29); // true (2024 is a leap year)
QDate::isValid(2020, 2, 29); // true (2020 is a leap year)
QDate::isValid(2026, 2, 29); // false (2026 is not a leap year)
QDate::isValid(2100, 2, 29); // false (2100 is not a leap year)
QDate::isValid(1202, 6, 6); // true (even though 1202 is pre-Gregorian)
See also
isNull(), setDate()
QString QDate::longDayName ( int  weekday,
MonthNameType  type = DateFormat 
)
static

Returns the long name of the weekday for the representation specified by type. The day names will be localized according to the system's default locale settings. Returns an empty string if the date is invalid.

Days are named using the following data.

  • 1 = "Monday"
  • 2 = "Tuesday"
  • 3 = "Wednesday"
  • 4 = "Thursday"
  • 5 = "Friday"
  • 6 = "Saturday"
  • 7 = "Sunday"
See also
longMonthName(), shortDayName(), shortMonthName(), toString()
QString QDate::longMonthName ( int  month,
MonthNameType  type = DateFormat 
)
static

Returns the long name of the month for the representation specified by type. The month names will be localized according to the system's default locale settings. Returns an empty string if the date is invalid.

Months are named using the following data.

  • 1 = "January"
  • 2 = "February"
  • 3 = "March"
  • 4 = "April"
  • 5 = "May"
  • 6 = "June"
  • 7 = "July"
  • 8 = "August"
  • 9 = "September"
  • 10 = "October"
  • 11 = "November"
  • 12 = "December"
See also
longDayName(), shortMonthName(), shortDayName(), toString()
int QDate::month ( ) const

Returns the month for this QDate using the following data.

  • 1 = "January"
  • 2 = "February"
  • 3 = "March"
  • 4 = "April"
  • 5 = "May"
  • 6 = "June"
  • 7 = "July"
  • 8 = "August"
  • 9 = "September"
  • 10 = "October"
  • 11 = "November"
  • 12 = "December"
See also
day(), year()
bool QDate::operator!= ( const QDate &  other) const
inline

Returns true if this QDate is not equal to other, otherwise returns false.

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

Returns true if this QDate is earlier than other, otherwise returns false.

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

Returns true if this QDate is earlier than or equal to other, otherwise returns false.

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

Returns true if this QDate is equal to other, otherwise returns false.

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

Returns true if this QDate is later than other, otherwise returns false.

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

Returns true if this QDate is later than or equal to other, otherwise returns false.

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

Sets this QDate using year, month, and day. Returns true if the date is valid, otherwise returns false. If the specified date is invalid, the QDate is set to be invalid. Any date before January 2, 4713 BCE is considered invalid.

See also
isValid()
QString QDate::shortDayName ( int  weekday,
MonthNameType  type = DateFormat 
)
static

Returns the short name of the weekday for the representation specified by type. The day names will be localized according to the system's default locale settings. Returns an empty string if the date is invalid.

Days named using the following data.

  • 1 = "Mon"
  • 2 = "Tue"
  • 3 = "Wed"
  • 4 = "Thu"
  • 5 = "Fri"
  • 6 = "Sat"
  • 7 = "Sun"
See also
longMonthName(), longDayName(), shortMonthName(), toString()
QString QDate::shortMonthName ( int  month,
MonthNameType  type = DateFormat 
)
static

Returns the short name of the month for the representation specified by type. The month names will be localized according to the system's default locale settings. Returns an empty string if the date is invalid.

Months are named using the following data.

  • 1 = "Jan"
  • 2 = "Feb"
  • 3 = "Mar"
  • 4 = "Apr"
  • 5 = "May"
  • 6 = "Jun"
  • 7 = "Jul"
  • 8 = "Aug"
  • 9 = "Sep"
  • 10 = "Oct"
  • 11 = "Nov"
  • 12 = "Dec"
See also
longDayName(), longMonthName(), shortDayName(), toString()
QDateTime QDate::startOfDay ( const QTimeZone zone = default_tz()) const

Returns the first millisecond of the current QDate in the given zone. If no time zone is passed then the local time zone will be used.

See also
endOfDay()
constexpr qint64 QDate::toJulianDay ( ) const
inlineconstexpr

Converts this QDate to an integer Julian day.

See also
fromJulianDay()
std::chrono::sys_days QDate::toStdSysDays ( ) const
inline

Returns the number of days between January 1, 1970 and this QDate. If the current Qate is before January 1, 1970 the number of days will be negative.

Note
This method is only available if your compiler supports the C++20 features of std::chrono.
See also
daysTo(), fromStdSysDays()
QString QDate::toString ( const QString format) const

Returns this QDate as a string. The format determines how the result will be formatted. If the QDate is invalid an empty string will be returned.

The following expressions can be used as part of the format. If any other characters are used in the format they will be treated as literal text. Any sequence of characters which are enclosed in single quotes will also be treated as literal text.

ExpressionOutput
d The day as number without a leading zero (1 to 31)
dd The day as number with a leading zero (01 to 31)
ddd The abbreviated localized day name (e.g. 'Mon' to 'Sun'). Uses QDate::shortDayName().
dddd The long localized day name (e.g. 'Monday' to 'Sunday'). Uses QDate::longDayName().
M The month as number without a leading zero (1 to 12)
MM The month as number with a leading zero (01 to 12)
MMM the abbreviated localized month name (e.g. 'Jan' to 'Dec'). Uses QDate::shortMonthName().
MMMM The long localized month name (e.g. 'January' to 'December'). Uses QDate::longMonthName().
yy The year as two digit number (00 to 99)
yyyy The year as four digit number. If the year is negative, a minus sign is prepended in addition.

The following examples use a QDate of 25 August 1995.

FormatResult
dd.MM.yyyy 25.08.1995
ddd MMMM d yy Fri Aug 25 95
'The day is' dddd The day is Friday
See also
fromString(), QDateTime::toString(), QTime::toString()
QString QDate::toString ( Qt::DateFormat  format = Qt::TextDate) const

Returns the current QDate as a string based on the given format. If the QDate is invalid then an empty string will be returned.

  • Qt::TextDate formats the string using the default as specified in the Qt::DateFormat enum. An example of this formatting is "Tue May 20 2008".
  • Qt::ISODate uses the ISO 8601 extended specification of yyyy-MM-dd. This format is only valid for years in the range 0 to 9999.
  • Qt::RFC2822Date uses the specification d MMM yyyy.
  • Qt::SystemLocaleShortDate or Qt::SystemLocaleLongDate will format the string based on the locale settings of the current system.
today.toString(Qt::SystemLocaleShortDate); // line A
QLocale::system().toString(today, QLocale::ShortFormat); // equivalent to calling line A
today.toString(Qt::SystemLocaleLongDate); // line B
QLocale::system().toString(today, QLocale::LongFormat); // equivalent to calling line B
  • Qt::DefaultLocaleShortDate or Qt::DefaultLocaleLongDate formats the string depends on the default application locale. This is the locale set with QLocale::setDefault() or the system locale if no default locale has been set.
today.toString(Qt::DefaultLocaleShortDate); // line C
QLocale().toString(today, QLocale::ShortFormat); // equivalent to calling line C
today.toString(Qt::DefaultLocaleLongDate); // line D
QLocale().toString(today, QLocale::LongFormat); // equivalent to calling line D
See also
fromString(), Qt::DateFormat
int QDate::weekNumber ( int *  yearNumber = nullptr) const

Populates the value of the pointer yearNumber with the year for this QDate. If yearNumber is a nullptr it will not be populated with a value. Returns the week number (1 to 53) for this QDate and 0 if the date is invalid.

In accordance with ISO 8601 weeks start on Monday and the first Thursday of a year is always in week 1 of that year. Most years have 52 weeks, but some have 53.

The value for yearNumber is not always the same as year(). For example, January 1 2000 is a Saturday and the week number is 52, which is part of the year 1999. The date December 31, 2002 is a Tuesday and is week number 1 of 2003.

See also
isValid()
int QDate::year ( ) const

Returns the year of this QDate. A negative value indicates a year before 1 CE. For example, -44 would be the year 44 BCE. This method returns 0 if QDate is invalid.

See also
day(), month()

Friends And Related Function Documentation

QDataStream & operator<< ( QDataStream stream,
const QDate &  date 
)
friend

Writes the given date to the stream. Returns a reference to the stream.

Refer to Serializing Data Types for additional information.

QDataStream & operator>> ( QDataStream stream,
QDate &  date 
)
friend

Reads from the stream into the given date. Returns a reference to the stream.

Refer to Serializing Data Types for additional information.