QDate 类

成员函数说明

构建一个QDate对象，其表示与date相同的日期。这允许标准库日历类和Qt datetime类之间轻松互操作。

例如

// 23 April 2012:
QDate date = std::chrono::year_month_day(std::chrono::year(2012),
                                         std::chrono::month(4),
                                         std::chrono::day(23));

// Same, under `using std::chrono` convenience:
QDate dateWithLiterals1 = 23 / April / 2012y;
QDate dateWithLiterals2 = 2012y / April / 23;

// Last day of February 2000
QDate lastDayFeb2020 = 2000y / February / last;

// First Monday of January 2020:
QDate firstMonday = 2020y / January / Monday[0];

// Last Monday of January 2020:
QDate lastMonday = 2020y / January / Monday[last];

此功能是在Qt 6.4中引入的。

返回日期字符串表示形式。参数format确定结果字符串的格式。如果提供了cal，则它确定表示日期所使用的日历；默认为公历。在Qt 5.14之前，没有cal参数，并且总是使用公历。

可以在format参数中使用以下表达式

用单引号括起来的任意字符序列将按原样包含在输出字符串中（去掉引号），即使它包含格式化字符。连续的两个单引号("''")在输出中替换为单个引号。格式字符串中的所有其他字符都将按原样包含在输出字符串中。

支持无分隔符的格式（例如“ddMM”），但必须谨慎使用，因为生成的字符串不一定总是可靠易读的（例如，“dM”生成“212”，可能表示12月2日或2月21日）。

示例格式字符串（假设QDate为1969年7月20日）

如果日期时间无效，将返回空字符串。

另请参阅 fromString(), QDateTime::toString(), QTime::toString(), 和 QLocale::toString。

[constexpr] QDate::QDate()

构造一个空日期。空日期无效。

另请参阅 isNull() 和 isValid。

QDate::QDate(int y, int m, int d)

使用年y、月m 和 日d 构造日期。

这个日期以格里高利历为基准。如果指定的日期无效，日期未被设置，并且isValid() 返回 false。

另请参阅 isValid() 和 QCalendar::dateFromParts。

QDate QDate::addDays(qint64 ndays) const

返回一个QDate对象，包含比此对象日期晚ndays天的日期（如果是负数，则较早）。

如果当前日期无效或新日期超出范围，则返回空日期。

另请参阅 addMonths(), addYears(), 和 daysTo。

[since 6.4] QDate QDate::addDuration(std::chrono::days ndays) const

返回一个QDate对象，包含比此对象日期晚ndays天的日期（如果是负数，则较早）。

如果当前日期无效或新日期超出范围，则返回空日期。

此功能是在Qt 6.4中引入的。

另请参阅 addMonths(), addYears(), 和 daysTo。

QDate QDate::addMonths(int nmonths, QCalendar cal) const

返回一个QDate对象，该对象包含晚于本对象日期nmonths的日期（如果nmonths为负数，则为早于本对象的日期）。

如果提供，则使用cal作为日历，否则使用格里高利日历。

参见：addDays()和addYears。

QDate QDate::addMonths(int nmonths) const

这是一个重载函数。

QDate QDate::addYears(int nyears, QCalendar cal) const

返回一个QDate对象，该对象包含晚于本对象日期nyears的日期（如果nyears为负数，则为早于本对象的日期）。

如果提供，则使用cal作为日历，否则使用格里高利日历。

参见：addDays()和addMonths。

QDate QDate::addYears(int nyears) const

这是一个重载函数。

[static] QDate QDate::currentDate()

返回系统时钟的当前日期。

参见：QTime::currentTime()和QDateTime::currentDateTime。

int QDate::day(QCalendar cal) const

返回此日期的月份日。

如果提供，则使用cal作为日历，否则使用格里高利日历（其返回值范围为1到31）。如果日期无效，则返回0。

参见：year()，month()，dayOfWeek()和QCalendar::partsFromDate。

int QDate::day() const

这是一个重载函数。

int QDate::dayOfWeek(QCalendar cal) const

返回此日期的星期几（1 = 星期一到7 = 星期日）。

如果提供，则使用cal作为日历，否则使用格里高利日历。如果日期无效，则返回0。一些日历可能赋予大于7的值特殊含义（例如闰日）。

另请参阅 day()，dayOfYear()，QCalendar::dayOfWeek()，以及 Qt::DayOfWeek。

int QDate::dayOfWeek() const

这是一个重载函数。

int QDate::dayOfYear(QCalendar cal) const

返回该日期的年内的日（第1天为1）。

如果提供，使用 cal 作为日历，否则使用公历。如果日期或其年份的第一天无效，则返回0。

另请参阅 day()，dayOfWeek()，以及 QCalendar::daysInYear（）。

int QDate::dayOfYear() const

这是一个重载函数。

int QDate::daysInMonth(QCalendar cal) const

返回此日期月份中的天数。

如果提供，则使用 cal 作为日历，否则使用公历（结果范围从28到31）。如果日期无效，则返回0。

另请参阅 day()，daysInYear()，QCalendar::daysInMonth（），QCalendar::maximumDaysInMonth（），以及 QCalendar::minimumDaysInMonth（）。

int QDate::daysInMonth() const

这是一个重载函数。

int QDate::daysInYear(QCalendar cal) const

返回此日期一年中的天数。

如果提供，则使用 cal 作为日历，否则使用公历（结果为365或366）。如果日期无效，则返回0。

另请参阅 day()，daysInMonth()，QCalendar::daysInYear（），以及 QCalendar::maximumMonthsInYear（）。

int QDate::daysInYear() const

这是一个重载函数。

qint64 QDate::daysTo(QDate d) const

返回从该日期到 d（如果 d 早于该日期则为其负数）的天数。

如果日期无效，则返回0。

示例

QDate d1(1995, 5, 17);  // May 17, 1995
QDate d2(1995, 5, 20);  // May 20, 1995
d1.daysTo(d2);          // returns 3
d2.daysTo(d1);          // returns -3

另请参阅 addDays（）。

QDateTime QDate::endOfDay(const QTimeZone &zone) const

返回一天的结束时刻。

一天何时结束取决于时间描述方式：对于在西部的时区中的人而言，每一天的开始和结束都要早些，对于在东部时区中的人而言则要晚些。可以通过可选的时间 zone 来指定要使用的时间表示法。默认的时间表示是系统的本地时间。

通常，一天的结束是在午夜前1毫秒，24:00，但是，如果时区转换导致给定的日期跳过这一时刻（例如，夏令时春季向前跳过23:00以及随后的一个小时），则返回这一天实际的最晚时间。这种情况只有在时间表示法是时区或本地时间时才会发生。

当区域的timeSpec()为Qt::OffsetFromUTC或Qt::UTC时，时间表示没有过渡，所以一天结束时为QTime(23, 59, 59, 999)。

在罕见的情况下，日期全部跳过（这发生在国际日期变更线东边的区域变为西边时），返回值无效。传入无效的区域作为区域将导致无效的结果，同样也适用于超出由QDateTime表示范围的日期。

另请参阅 startOfDay。

[自 6.5 开始] QDateTime QDate::endOfDay() const

这是一个重载函数。

此函数自Qt 6.5版本开始引入。

[静态常量] QDate QDate::fromJulianDay(qint64 jd)

将儒略日jd转换为QDate。

另请参阅 toJulianDay。

[静态常量 noexcept, 自 6.4 开始] QDate QDate::fromStdSysDays(const std::chrono::sys_days &days)

返回自1970年1月1日（UNIX纪元）起的QDate days天后。如果days为负数，返回的日期将在纪元之前。

此功能是在Qt 6.4中引入的。

另请参阅 toStdSysDays。

[静态] QDate QDate::fromString(const QString &string, Qt::DateFormat format = Qt::TextDate)

使用提供的format将字符串string表示为QDate，如果无法解析字符串，则返回无效日期。

关于Qt::TextDate的说明：只识别英文月份名称（例如“Jan”为短格式或“January”为长格式）。

另请参阅 toString()和QLocale::toDate。

[静态，自 6.0 开始] QDate QDate::fromString(QStringView string, Qt::DateFormat format = Qt::TextDate)

这是一个重载函数。

此函数自Qt 6.0版本开始引入。

[静态，自 6.0 开始] QDate QDate::fromString(QStringView string, QStringView format, QCalendar cal)

这是一个重载函数。

此函数自Qt 6.0版本开始引入。

[静态，自 6.0 开始] QDate QDate::fromString(const QString &string, QStringView format, QCalendar cal)

这是一个重载函数。

此函数自Qt 6.0版本开始引入。

[静态] QDate QDate::fromString(const QString &string, const QString &format, QCalendar cal)

这是一个重载函数。

[静态，自6.7起] QDate QDate::fromString(QStringView string, QStringView format, int baseYear = QLocale::DefaultTwoDigitBaseYear)

这是一个重载函数。

使用默认构造的 QCalendar。

此函数自Qt 6.7版本引入。

[静态，自6.7起] QDate QDate::fromString(QStringView string, QStringView format, int baseYear, QCalendar cal)

这是一个重载函数。

此函数自Qt 6.7版本引入。

[静态，自6.7起] QDate QDate::fromString(const QString &string, QStringView format, int baseYear = QLocale::DefaultTwoDigitBaseYear)

这是一个重载函数。

使用默认构造的 QCalendar。

此函数自Qt 6.7版本引入。

[静态，自6.0起] QDate QDate::fromString(const QString &string, QStringView format, int baseYear, QCalendar cal)

这是一个重载函数。

此函数自Qt 6.0版本开始引入。

[静态，自6.7起] QDate QDate::fromString(const QString &string, const QString &format, int baseYear = QLocale::DefaultTwoDigitBaseYear)

这是一个重载函数。

使用默认构造的 QCalendar。

此函数自Qt 6.7版本引入。

[静态] QDate QDate::fromString(const QString &string, const QStringView &format, int baseYear, QCalendar cal)

使用提供的format将字符串string表示为QDate，如果无法解析字符串，则返回无效日期。

如果提供，使用 cal 作为日历，否则使用公历。以下格式描述中值的范围是指后者；对于其他日历，这些值可能不同。

以下表达式可用于格式

所有其他输入字符都将按文本处理。任何用单引号括起来的非空字符序列也将按文本处理（移除引号）并不被视为表达式。例如

QDate date = QDate::fromString("1MM12car2003", "d'MM'MMcaryyyy");
// date is 1 December 2003

如果格式不满足，将返回一个无效的 QDate。不期望首部零（d，M）的表达式将是贪婪的。这意味着即使这会使它们超出接受的值范围，它们也将使用两位数字，并使其他部分的数字太少。例如，以下格式字符串本可以表示1月30日，但M将捕获两位数字，导致无效日期

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

对于格式中没有表示的字段，以下为默认值

当格式只指定年份的最后两位时，从baseYear开始的100年是首先考虑的候选年份。在6.7版本之前没有baseYear参数，始终使用1900。这是baseYear的默认值，从中选择到1999年。例如，将1976作为baseYear将选择从1976年到2075年的年份。当格式还包含月份、星期几（月中的日子）和星期几时，这些信息足以暗示世纪。在这种情况下，会选择与baseYear指示的最近一个世纪相对应的匹配日期，优先选择较晚的而不是较早的。有关更多详细信息，请参阅QCalendar::matchCenturyToWeekday()及日期歧义问题。

以下示例演示了默认值

QDate::fromString("1.30", "M.d");           // January 30 1900
QDate::fromString("20000110", "yyyyMMdd");  // January 10, 2000
QDate::fromString("20000110", "yyyyMd");    // January 10, 2000

日期歧义问题

不同的文化使用不同的日期格式，因此用户可能会混淆应该提供日期字段的顺序。例如，"Wed 28-Nov-01"可能表示2028年11月1日或2001年11月28日（幸运的是，两者都是星期三）。使用格式"ddd yy-MMM-dd"应将其解释为第一种方式，使用"ddd dd-MMM-yy"则解释为第二种方式。然而，用户的意思可能取决于用户通常如何书写日期，而不是代码期望的格式。

上面考虑的例子混淆了月份和两位数的年份。类似的混淆也可能发生在月份和月份的日互换时，当它们都被当作数字提供时。在这种情况下，在日期格式中包含一个星期几字段可以提供一些冗余，可能有助于捕获此类错误。然而，就像上面的例子一样，这并不总是有效的：两个字段（或它们的含义）的互换可能生成具有相同星期几的日期。

在格式中包含一个星期几也可以解决仅使用年份的最后两位数的日期的世纪。不幸的是，当与用户（或其他数据来源）混合了两个字段的数据结合时，这种解决方案可能会导致找到与格式读取匹配但不是作者意图的日期。同样，如果用户只在一个完全正确的日期中犯了星期几的错误，这也可能导致在不同的世纪中找到日期。在任何情况下，找到不同世纪的日期都可能将错误输入的日期变成完全不同的日期。

避免日期歧义的最好方法是使用四位数的年份，并使用名称指定的月份（无论是全称还是缩写），理想情况下是通过用户界面习语收集的，这些习语向用户清晰地表明他们选择的日期部分。包括一个星期几也可以通过提供检查数据一致性的手段来帮助。当来自用户的数据时，使用用户选择的区域设置提供的格式最好，因为简短格式更有可能使用两位数的年份。当然，并不是总有可能控制格式——数据可能来自一个你不控制的来源，例如。

由于这些可能的混淆来源，尤其是在您无法确定是否正在使用清晰格式的情形下，检查读取字符串作为日期的结果不仅有效，而且符合其提供目的，就非常重要。如果结果超出某些合理值范围，可能值得让用户确认他们的日期选择，以长格式显示从字符串中读取的日期，包括月份名称和四位年份，以使识别任何错误更加容易。

参见 toString()，QDateTime::fromString()，QTime::fromString() 和 QLocale::toDate。

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

提取日期的年、月和日，并将它们分配给 *year，*month 和 *day。这些指针可以是 null。

如果日期无效，返回 0。

参见 year()，month()，day()，isValid() 和 QCalendar::partsFromDate ()。

[静态] bool QDate::isLeapYear(int year)

如果指定 year 在公历中为闰年，则返回 true；否则返回 false。

参见 QCalendar::isLeapYear ()。

[constexpr] bool QDate::isNull() const

如果日期为 null，则返回 true；否则返回 false。null 日期是无效的。

参见 isValid ()。

[constexpr] bool QDate::isValid() const

如果此日期有效，则返回 true；否则返回 false。

参见 isNull () 和 QCalendar::isDateValid ()。

[static] bool QDate::isValid(int year, int month, int day)

这是一个重载函数。

如果指定日期 year，month 和 day 在公历中有效，则返回 true；否则返回 false。

示例

QDate::isValid(2002, 5, 17);  // true
QDate::isValid(2002, 2, 30);  // false (Feb 30 does not exist)
QDate::isValid(2004, 2, 29);  // true (2004 is a leap year)
QDate::isValid(2000, 2, 29);  // true (2000 is a leap year)
QDate::isValid(2006, 2, 29);  // false (2006 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)

参见 isNull ()，setDate () 和 QCalendar::isDateValid ()。

int QDate::month(QCalendar cal) const

返回日期的月份编号。

从 1 开始编号年份的月份。如果提供了，使用 cal 作为日历，否则为公历，其月份编号如下

• 1 = "January"
• 2 = "February"
• 3 = "March"
• 4 = "四月"
• 5 = "五月"
• 6 = "六月"
• 7 = "七月"
• 8 = "八月"
• 9 = "九月"
• 10 = "十月"
• 11 = "十一月"
• 12 = "十二月"

如果日期无效，则返回0。注意，有些日历在某些年份中可能包含超过12个月。

另请参阅 year()，day() 和 QCalendar::partsFromDate。

int QDate::month() const

这是一个重载函数。

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

将此设置为表示格里历中给定年、月和日编号的日期。如果结果日期有效，则返回true；否则，将此设置为表示无效日期并返回false。

另请参阅 isValid() 和 QCalendar::dateFromParts。

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

将此设置为表示在给定日历cal中给定年、月和日编号的日期。如果结果日期有效，则返回true；否则，将此设置为表示无效日期并返回false。

另请参阅 isValid() 和 QCalendar::dateFromParts。

QDateTime QDate::startOfDay(const QTimeZone &zone) const

返回一天的开始时刻。

一天的开始取决于对时间的描述：对于位于更西时区的人来说，每天的开始和结束较早；对于位于更东时区的人来说，每天的开始和结束较晚。可以通过可选的时间时区来指定要使用的时间表示。默认的时间表示是系统的本地时间。

通常，一天的开始是午夜，00:00。但是，如果时区转换导致给定日期跳过那个午夜（例如，夏令时春分跳过一天的第一小时），则返回一天的最早实际时间。这种情况只会在时间表示为时区或本地时间时发生。

当时区的timeSpec()为Qt::OffsetFromUTC或Qt::UTC时，时间表示没有转换，因此一天的开始是QTime(0, 0)。

在极少数情况下，日期完全被跳过的情况下（这发生在位于国际日期变更线以东的时区切换到在西边时），返回值将无效。将无效的时区传递给时区也将产生无效的结果，就像日期的开始超出了QDateTime可表示的范围时一样。

另请参阅 endOfDay。

[since 6.5] QDateTime QDate::startOfDay() const

这是一个重载函数。

此函数自Qt 6.5版本开始引入。

[constexpr] qint64 QDate::toJulianDay() const

将日期转换为儒略日。

另请参阅 fromJulianDay。

[constexpr noexcept] std::chrono::sys_days QDate::toStdSysDays() const

返回自1970年1月1日（UNIX纪元）至该日期之间的天数，以 std::chrono::sys_days 对象表示。如果此日期早于纪元，则天数将是负数。

另请参阅 fromStdSysDays() 以及 daysTo()。

QString QDate::toString(Qt::DateFormat format = Qt::TextDate) const

这是一个重载函数。

将日期作为字符串返回。参数 format 决定了字符串的格式。

如果 format 为 Qt::TextDate，字符串将按照默认方式格式化。日期和月份名称将是英语。此格式的示例是 "Sat May 20 1995"。有关本地化格式，请参阅 QLocale::toString。

如果 format 为 Qt::ISODate，字符串格式符合ISO 8601扩展规范中的日期和时间表示格式，格式为 yyyy-MM-dd，其中 yyyy 年份，MM 一年中的月份（介于 01 和 12 之间），dd 是一个月中的天数（介于 01 和 31 之间）。

如果 format 为 Qt::RFC2822Date，字符串将按照RFC 2822兼容的方式格式化。此格式的示例是 "20 May 1995"。

如果日期无效，将返回空字符串。

另请参阅 fromString() 以及 QLocale::toString。

QString QDate::toString(const QString &format) const

这是一个重载函数。

QString QDate::toString(QStringView format) const

这是一个重载函数。

int QDate::weekNumber(int *yearNumber = nullptr) const

返回ISO 8601周数（1到53）。

如果日期无效，返回0。否则，返回该日期的周数。如果 yearNumber 不是 nullptr（默认值），则将年份存储为 *yearNumber。

根据ISO 8601，每周属于该年，其中包含最多的一天，在格里历中。由于ISO 8601的周从星期一开始，所以这是该周的星期四所在的年份。大多数年份有52周，但有些有53周。

参见 isValid ()。

int QDate::year(QCalendar cal) const

返回此日期的年份。

如果提供，则使用cal作为日历，否则使用格里高利日历。

如果日期无效，返回0。对于某些日历，最早年份之前的所有日期都可能是无效的。

如果使用有公元0年的日历，请使用isValid()检查返回值是否为0。此类日历以明显的方式使用负年份，例如，年份1之后是年份0，再之后是年份-1，依此类推。

一些日历虽然没有公元0年，却在第一年之前采用传统年份编号，从1年倒数。例如，在儒略历的推算历中，公元1年（第一年）之前连续的年份标示为1 BC，2 BC，3 BC，依此类推。对于此类日历，使用负年份数字表示这些在1年之前的年份，其中-1表示1年之前的年份。

另外参见 month()，day()，QCalendar::hasYearZero()，QCalendar::isProleptic()和QCalendar::partsFromDate。

int QDate::year() const

这是一个重载函数。