QDate Class

成员函数文档

[constexpr] QDate::QDate()

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

另请参阅 isNull() 和isValid()。

构建一个QDate 对象，其日期与date 表示的日期相同。这使得标准库中的日历类与Qt的日期时间类之间能够轻松实现互操作。

例如：

// 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 = 23d / 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 中引入。

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

构建一个日期，其中年份为y ，月份为m ，日期为d 。

该日期基于公历进行解释。如果指定的日期无效，则不会设置该日期，且isValid() 会返回false 。

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

QDate QDate::addDays(qint64 ndays) const

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

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

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

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

返回一个QDate 对象，其中包含一个比该对象日期更晚的日期ndays （如果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）。

如果提供了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.toJulianDay() - toJulianDay() 。如果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 指定要使用的时间表示法。默认时间表示法为系统的本地时间。

通常，一天的结束时间是午夜 24:00 前的一毫秒： 然而，如果时区转换导致给定日期跳过了该时刻（例如，夏令时“春进”跳过了23:00及随后的一小时），则将返回该日实际的最新时间。这种情况仅在时间表示形式为时区或本地时间时才会发生。

当zone 的timeSpec()为Qt::OffsetFromUTC 或Qt::UTC 时，该时间表示形式不存在时区转换，因此一天的结束时间为QTime （23, 59, 59, 999）。

在极少数情况下，如果某个日期被完全跳过（这发生在位于国际日期变更线以东的时区切换到以西时），返回值将无效。传入无效时区（如zone ）也会产生无效结果，同样，结束时间超出QDateTime 可表示范围的日期也会产生无效结果。

另请参阅 startOfDay()。

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

该函数在 Qt 6.5 中引入。

[static constexpr] QDate QDate::fromJulianDay(qint64 jd)

将儒略日jd 转换为QDate 。

另请参阅 toJulianDay()。

[static constexpr noexcept, since 6.4] QDate QDate::fromStdSysDays(const std::chrono::sys_days &days)

返回自1970年1月1日（UNIX纪元）起经过days 天后的QDate 。如果days 为负数，则返回的日期将早于纪元。

该函数在 Qt 6.4 中引入。

另请参阅 toStdSysDays()。

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

返回由string 表示的QDate ，使用给定的format ；如果无法解析该字符串，则返回一个无效日期。

若提供了cal ，则使用该日历；否则使用公历。下文格式说明中的数值范围适用于公历；对于其他日历，这些范围可能有所不同。

以下表达式可用于该格式：

任何用单引号括起的非空字符序列也将被视为文本（去除引号），而非表达式。 两个连续的单引号（"''"）将被视为一个单引号，用于与输入内容匹配，而不是作为原样序列的开头或结尾。所有其他输入字符都将被视为原样文本，用于与输入字符串进行匹配。例如：

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

如果不符合格式要求，将返回一个无效的QDate 。

当数值字段并列且没有分隔符来分割数字序列时，可能会出现歧义：某些允许使用一位数的字段是否应使用两位数（因为要表示的值大于9）。 若为该字段分配两位数会导致其他字段可用位数不足，且单个位数的读数与其他字段一致，则可解决此歧义。 否则（即允许多个字段仅使用一位数，且若每个字段仅使用一位数仍会有剩余位数时），在数据保持一致的前提下，应优先采用将额外位数分配给前序字段的处理方式，而非分配给后序字段。例如：

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

对于任何未以该格式表示的字段，将采用以下默认设置：

当format 仅指定年份的后两位数字时，首先考虑的候选年份是从baseYear 开始的100个年份。 在 6.7 版本之前，不存在baseYear 参数，系统始终使用 1900 年。这是baseYear 的默认行为，即从该年到 1999 年之间选择一年。例如，若将 1976 作为baseYear 参数传入，则将从 1976 年到 2075 年之间选择一年。 当日期格式同时包含月份、日期（当月）和星期几时，这些信息足以推断出世纪。在这种情况下，系统会在与baseYear 所指世纪最接近的世纪中选择一个匹配的日期，且优先选择较晚的日期而非较早的。更多详细信息请参阅QCalendar::matchCenturyToWeekday() 和Date ambiguities ，

以下示例演示了默认值：

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

[static, since 6.0] QDate QDate::fromString(QStringView string, Qt::DateFormat format = Qt::TextDate)

该函数在 Qt 6.0 中引入。

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

返回由string 表示的QDate ，使用给定的format ；如果无法解析该字符串，则返回一个无效日期。

关于Qt::TextDate 的说明：仅识别英文月份名称（例如简写形式的“Jan”或全称形式的“January”）。

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

[static, since 6.0] QDate QDate::fromString(QStringView string, QStringView format, QCalendar cal)

该函数是在 Qt 6.0 中引入的。

[static, since 6.7] QDate QDate::fromString(QStringView string, QStringView format, int baseYear = QLocale::DefaultTwoDigitBaseYear)

使用默认构造的QCalendar 。

该函数在 Qt 6.7 中引入。

[static, since 6.0] QDate QDate::fromString(const QString &string, QStringView format, QCalendar cal)

该函数在 Qt 6.0 中引入。

[static, since 6.7] QDate QDate::fromString(const QString &string, QStringView format, int baseYear = QLocale::DefaultTwoDigitBaseYear)

使用默认构造的QCalendar 。

该函数在 Qt 6.7 中引入。

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

[static, since 6.7] QDate QDate::fromString(const QString &string, const QString &format, int baseYear = QLocale::DefaultTwoDigitBaseYear)

使用默认构造的QCalendar 。

该函数在 Qt 6.7 中引入。

[static, since 6.7] QDate QDate::fromString(QStringView string, QStringView format, int baseYear, QCalendar cal)

该函数在 Qt 6.7 中引入。

[static, since 6.0] QDate QDate::fromString(const QString &string, QStringView format, int baseYear, QCalendar cal)

该函数在 Qt 6.0 中引入。

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

提取日期的年、月和日，并将它们分别赋值给 *year 、*month 和 *day 。这些指针可能为空。

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

另请参阅 year()、month()、day()、isValid() 和QCalendar::partsFromDate()。

[static] bool QDate::isLeapYear(int year)

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

另请参阅 QCalendar::isLeapYear()。

[constexpr] bool QDate::isNull() const

如果日期为空，则返回true ；否则返回false 。空日期是不合法的。

另请参阅 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 = “一月”
• 2 = “二月”
• 3 = “三月”
• 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)

将此参数设置为格里高利历中对应给定year 、month 和day 数值的日期。如果生成的日期有效，则返回true；否则，将此参数设置为表示无效日期并返回false。

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

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

将此参数设置为表示在指定日历cal 中，由给定的year 、month 和day 数值构成的日期。如果生成的日期有效，则返回 true；否则，将此参数设置为表示一个无效日期并返回 false。

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

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

返回该日的开始时刻。

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

通常，一天的开始是午夜 00:00；但是，如果时区转换导致给定日期跳过了该午夜（例如，夏令时“春进”跳过了当天第一小时），则返回该天实际最早的时间。 这种情况仅在时间表示形式为时区或本地时间时才会发生。

当zone 的timeSpec()为Qt::OffsetFromUTC 或Qt::UTC 时，该时间表示形式不存在时区转换，因此一天的开始时间为QTime(0, 0)。

在极少数情况下，若某日期被完全跳过（这发生在位于国际日期变更线以东的时区切换至以西时），则返回结果将无效。将无效时区作为zone 参数传入也会产生无效结果，同样，起始时间超出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()。

将日期作为字符串返回。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()。

QString QDate::toString(QStringView format) const

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

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 年，第 0 年之前是第 -1 年，以此类推。

某些历法虽然没有公元元年，但对其第一年之前的年份采用从 1 开始倒计数的惯用编号方式。例如，在推算格里高利历中，公元 1 年（第一年）之前的连续年份分别标识为公元前 1 年、公元前 2 年、公元前 3 年，以此类推。 对于此类历法，负年号用于表示公元1年之前的年份，其中“-1”表示公元1年之前的一年。

另请参阅 month()、day()、QCalendar::hasYearZero()、QCalendar::isProleptic() 以及QCalendar::partsFromDate()。

int QDate::year() const