Класс QDate

Класс QDate предоставляет функции работы с датами. Подробнее...

• Список всех членов, включая унаследованные

Примечание: Все функции этого класса являются повторно входящими.

Открытые функции

Статические открытые члены

Связанные нечлены

Подробное описание

Объект QDate представляет определенный день, независимо от календаря, локали или других настроек, используемых при его создании или предоставленных системой. Он может сообщать год, месяц и день месяца, представляющие день относительно пролептического григорианского календаря или любого календаря, предоставленного как объект QCalendar. Объекты QDate должны передаваться по значению, а не по ссылке на const; они просто упаковывают qint64.

Объект QDate обычно создается, явно задавая год, месяц и день. Обратите внимание, что QDate интерпретирует значения года, меньшие 100, как представленные, т.е., как года от 1 до 99, без добавления смещения. Статический метод currentDate() создает объект QDate, содержащий дату, считанную с системных часов. Явную дату также можно установить, используя setDate(). Функция fromString() возвращает QDate, заданный строкой и форматом даты, используемым для интерпретации даты в строке.

Функции year(), month() и day() обеспечивают доступ к значениям года, месяца и дня. Если требуется несколько значений, более эффективно вызывать QCalendar::partsFromDate() для экономии повторных (потенциально дорогостоящих) расчетов календаря.

Также предоставляются функции dayOfWeek() и dayOfYear(). Та же информация предоставляется в текстовом формате функцией toString(). QLocale может сопоставлять числовые значения дней с их названиями, QCalendar — числовые значения месяцев с их названиями.

QDate предоставляет полный набор операторов для сравнения двух объектов QDate, где меньшее значение соответствует более ранней дате, а большее — более поздней.

Вы можете увеличить (или уменьшить) дату на заданное количество дней, используя addDays(). Аналогичным образом, вы можете использовать addMonths() и addYears(). Функция daysTo() возвращает количество дней между двумя датами.

Функции daysInMonth() и daysInYear() возвращают количество дней в месяце и году этой даты соответственно. Функция isLeapYear() указывает, является ли год високосным. QCalendar также может предоставить эту информацию, в некоторых случаях более удобно.

Замечания

В григорианском календаре нет года 0. Даты в этом году считаются недопустимыми. Год -1 — год «за 1 год до Рождества Христова» или «за 1 год до общей эры». День перед 1 января 1 н. э., QDate(1, 1, 1), — 31 декабря 1 г. до н. э., QDate(-1, 12, 31). Аналогичным образом ведут себя и другие календари; см. QCalendar::hasYearZero().

Диапазон допустимых дат

Даты хранятся в памяти в виде числа Джулианского дня, целого числа, считающего каждый день в непрерывном диапазоне, где 24 ноября 4714 г. до н. э. в григорианском календаре соответствует дню Джулианского 0 (1 января 4713 г. до н. э. в юлианском календаре). Помимо того, что это эффективный и точный способ хранения абсолютной даты, он подходит для преобразования даты в другие календарные системы, такие как еврейская, исламская или китайская. Число Джулианского дня можно получить, используя QDate::toJulianDay(), и можно установить, используя QDate::fromJulianDay().

Диапазон чисел Джулианского дня, которые может представлять QDate, по техническим причинам ограничен значениями от -784350574879 до 784354017364, что означает период от до 2 миллиардов лет до н. э. до после 2 миллиардов лет н. э. Это более чем в семь раз шире диапазона дат, который может представлять QDateTime.

См. также QTime, QDateTime, QCalendar, QDateTime::YearRange, QDateEdit, QDateTimeEdit и QCalendarWidget.

Документация по членам функции

Возвращает дату в виде строки. Параметр format определяет формат результирующей строки. Если cal задан, он определяет календарь, используемый для представления даты; по умолчанию используется григорианский календарь.

Можно использовать следующие выражения:

Любая последовательность символов, заключённых в одинарные кавычки, будет включена в результирующую строку дословно (без кавычек), даже если она содержит символы форматирования. Две последовательные одинарные кавычки ("''") заменяются одной одинарной кавычкой в выводе. Все остальные символы в строке формата включаются в результирующую строку дословно.

Форматы без разделителей (например, "ddMM") поддерживаются, но использовать их следует с осторожностью, так как результирующие строки не всегда надёжно читаемы (например, если "dM" даёт "212", это может означать либо 2 декабря, либо 21 февраля).

Примеры строк формата (предполагается, что QDate — 20 июля 1969 г.):

Если дата недействительна, возвращается пустая строка.

См. также fromString(), QDateTime::toString(), QTime::toString() и QLocale::toString().

Возвращает конечный момент дня. Обычно это за миллисекунду до полуночи в конце дня: однако если переход зоны времени вызывает пропуск полуночи для заданной даты (например, переход на летнее время вперёд, пропуская время сразу после 23:00 и переходя к началу следующего дня), возвращается фактическое последнее время в течение дня. Это может произойти только в том случае, если начальный момент задан относительно зоны времени (передавая её QTimeZone как zone) или по местному времени (передавая Qt::LocalTime как spec; это значение по умолчанию).

offsetSeconds игнорируется, если spec не равен Qt::OffsetFromUTC, в противном случае оно представляет смещение зоны от UTC. Поскольку UTC и такие зоны не имеют переходов, конец дня — QTime(23, 59, 59, 999) в этих случаях.

В редких случаях, когда дата полностью пропускается (это происходит, когда зона, расположенная восточнее линии перемены дат, переключается на зону, расположенную западнее её), возвращаемое значение будет недействительным. Передача Qt::TimeZone в качестве spec (вместо передачи QTimeZone) также даст недействительный результат, как и даты, заканчивающиеся вне диапазона, представимого QDateTime.

Функция была добавлена в Qt 5.14.

См. также startOfDay().

Возвращает начальный момент дня. Обычно это полночь в начале дня: однако, если переход зоны времени вызывает пропуск полуночи для заданной даты (например, переход на летнее время вперёд, пропуская время сразу после 23:00 и переходя к началу следующего дня), возвращается фактическое самое раннее время в день. Это может произойти только в том случае, если начальный момент задан относительно зоны времени (передавая её QTimeZone как zone) или по местному времени (передавая Qt::LocalTime как spec; это значение по умолчанию).

offsetSeconds игнорируется, если spec не равен Qt::OffsetFromUTC, в противном случае оно представляет смещение зоны от UTC. Поскольку UTC и такие зоны не имеют переходов, начало дня — QTime(0, 0) в этих случаях.

В редких случаях, когда дата была полностью пропущена (это происходит, когда зона, расположенная к востоку от линии перемены дат, переходит к западу от неё), результат будет недействительным. Передача Qt::TimeZone в качестве spec (вместо передачи QTimeZone) или передача недопустимой временной зоны в качестве zone также приведут к недействительному результату, как и даты, начинающиеся вне диапазона, представимого QDateTime.

Эта функция была введена в Qt 5.14.

См. также endOfDay().

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

Создаёт дату с годом y, месяцем m и днём d.

Дата понимается в контексте григорианского календаря. Если указанная дата недействительна, дата не устанавливается, и isValid() возвращает false.

См. также isValid() и QCalendar::dateFromParts().

QDate::QDate()

Создаёт нулевую дату. Нулевые даты недействительны.

См. также isNull() и isValid().

QDate QDate::addDays(qint64 ndays) const

Возвращает объект QDate, содержащий дату, которая на ndays позже или раньше (если ndays отрицательно) даты этого объекта.

Возвращает нулевую дату, если текущая дата недействительна или новая дата выходит за пределы диапазона.

См. также 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().

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

Преобразует юлианский день jd в QDate.

См. также toJulianDay().

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

Возвращает QDate, представленную строкой string с использованием заданного format, или недействительную дату, если строка не может быть обработана.

Примечание для Qt::TextDate: распознаются только английские названия месяцев (например, "Jan" в краткой форме или "January" в полной форме).

См. также toString() и 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 = QCalendar())

Это перегруженная функция.

Эта функция была введена в Qt 6.0.

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

Это перегруженная функция.

Эта функция была введена в Qt 6.0.

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

Возвращает QDate, представленный строкой string, используя заданный формат, или недействительную дату, если строку невозможно разобрать.

Использует cal в качестве календаря, если он предоставлен, иначе — григорианский календарь. Диапазоны значений в описаниях форматов ниже относятся ко второму случаю; они могут отличаться для других календарей.

Эти выражения могут быть использованы для формата:

Все остальные символы входных данных будут обрабатываться как текст. Любая непустая последовательность символов, заключенная в одинарные кавычки, также будет обрабатываться (без кавычек) как текст и не будет интерпретироваться как выражение. Например:

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

Если формат не соответствует, возвращается недействительная QDate. Выражения, не ожидающие ведущих нулей (d, M), будут жадными. Это означает, что они будут использовать два знака, даже если это выведет их за пределы допустимого диапазона значений и оставит слишком мало знаков для других разделов. Например, следующая строка формата могла означать 30 января, но M захватит два знака, что приведёт к недействительной дате:

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

Для любого поля, не представленного в формате, используются следующие значения по умолчанию:

Следующие примеры демонстрируют значения по умолчанию:

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

См. также toString(), QDateTime::fromString(), QTime::fromString(), и QLocale::toDate().

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)

Возвращает true, если указанный год является високосным в григорианском календаре; в противном случае возвращает false.

См. также QCalendar::isLeapYear().

bool QDate::isNull() const

Возвращает true, если дата равна null; в противном случае возвращает false. Дата null недействительна.

См. также isValid().

bool QDate::isValid() const

Возвращает true, если эта дата действительна; в противном случае возвращает false.

См. также isNull() и QCalendar::isDateValid().

[static] bool QDate::isValid(int year, int month, int 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)

Устанавливает эту дату, чтобы она представляла дату в григорианском календаре, с заданными годом, месяцем и днём. Возвращает true, если полученная дата действительна, в противном случае устанавливает эту дату как недействительную и возвращает false.

См. также isValid() и QCalendar::dateFromParts().

[since 5.14] bool QDate::setDate(int year, int month, int day, QCalendar cal)

Устанавливает эту дату, чтобы она представляла дату в указанном календаре cal, с заданными годом, месяцем и днём. Возвращает true, если полученная дата действительна, в противном случае устанавливает эту дату как недействительную и возвращает false.

Эта функция была добавлена в Qt 5.14.

См. также isValid() и QCalendar::dateFromParts().

qint64 QDate::toJulianDay() const

Преобразует дату в юлианский день.

См. также fromJulianDay().

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

Это перегруженная функция.

Возвращает дату в виде строки. Параметр format определяет формат строки.

Если format равен Qt::TextDate, строка форматируется по умолчанию. Имена дней и месяцев будут на английском языке. Пример такого форматирования: "Сб Май 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 Май 1995".

Если дата недействительна, возвращается пустая строка.

См. также fromString() и QLocale::toString().

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 до н. э., 2 до н. э., 3 до н. э. и так далее. Для таких календарей используются отрицательные значения года для обозначения этих лет до года 1, где -1 обозначает год до 1.

См. также month(), day(), QCalendar::hasYearZero(), QCalendar::isProleptic(), и QCalendar::partsFromDate().

int QDate::year() const

Это перегруженный метод.