QDate Class

成员函数文档

构造一个与date 表示相同日期的QDate 。这样，标准库日历类和 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 = 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 ，该日期晚于此对象的日期（如果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 早于本日期，则天数为负）。

如果任一日期无效，则返回 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 前一毫秒：但是，如果时区转换导致给定日期跳过该时刻（例如，DST 跳过 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 的纪元）之后的QDate days 天数。如果days 为负数，返回的日期将在该纪元之前。

此函数在 Qt 6.4 中引入。

另请参阅 toStdSysDays().

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

使用给定的format 返回string 所代表的QDate ，如果字符串无法解析，则返回无效日期。

Qt::TextDate 的注意事项：只识别英文月份名称（如简写的 "Jan "或长写的 "January"）。

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

[static] QDate QDate::fromString(const QString &string, const QString &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

对于格式中没有表示的字段，将使用以下默认值：

当format 只指定年份的最后两位数时，从baseYear 开始的 100 年是首先考虑的候选年份。在 6.7 之前，没有baseYear 参数，总是使用 1900。这是baseYear 的默认设置，选择从 1900 年到 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, 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 = "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：但是，如果时区转换导致给定日期跳过午夜（例如，DST 跳过一天中的第一个小时），则会返回一天中实际最早的时间。只有当时间表示为时区或当地时间时，才会出现这种情况。

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

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 年，依此类推。

有些历法尽管没有 0 年，但对第一年之前的年份采用传统的编号方式，从 1 开始倒数。例如，在公元前的格里高利历中，公元前 1 年（第一年）之前的连续年份被标识为公元前 1 年、公元前 2 年、公元前 3 年，依此类推。在这种历法中，负年号用于表示第 1 年之前的年份，-1 表示第 1 年之前的年份。

另请参见 month(),day(),QCalendar::hasYearZero(),QCalendar::isProleptic() 和QCalendar::partsFromDate().

int QDate::year() const

这是一个重载函数。