Класс 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 также может предоставить эту информацию, в некоторых случаях более удобным способом.

Примечания

Примечание: Все преобразования в строковые форматы и из них выполняются с использованием C-локали. Для локализованных преобразований см. QLocale.

В григорианском календаре нет года 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 года):

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

Примечание: Имена дней и месяцев указаны на английском языке (C-локаль). Если нужны локализованные имена месяцев и дней, используйте QLocale::system().toString().

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

Возвращает начальный момент дня. Обычно это полночь в начале дня: однако, если переход к часовому поясу приводит к пропуску полуночи для данной даты (например, переход на летнее время, пропускающий время в конце предыдущего дня и переходя к 01: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.

Предупреждение: Годы от 1 до 99 интерпретируются как есть. Год 0 недействителен.

См. также 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, если он передан, в противном случае используется григорианский календарь.

Примечание: Если сочетание конечного дня/месяца не существует в получившемся году (например, для григорианского календаря, если дата была 29 февраля, а конечный год не високосный), эта функция вернет самую позднюю допустимую дату в данном месяце (в примере это 28 февраля).

См. также 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 с использованием заданного format, или недействительную дату, если строка не может быть обработана.

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

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

Примечание: Имена дней и месяцев должны быть на английском языке (C-локаль). Если используются локализованные имена месяцев и дней, используйте QLocale::system().toDate().

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

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, если дата недействительна.

Примечание: В версиях Qt до 5.7 эта функция помечена как не-const.

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

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

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

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

bool QDate::isNull() const

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

Примечание: Поведение этой функции эквивалентно isValid().

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

bool QDate::isValid() const

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

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

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

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

Возвращает true, если указанная дата (year, month и day) действительна в григорианском календаре; иначе возвращает 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().

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

Устанавливает эту дату в заданном календаре cal с заданными значениями года year, месяца month и дня day. Возвращает 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".

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

Предупреждение: Формат Qt::ISODate действителен только для годов в диапазоне от 0 до 9999.

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

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

Возвращает номер недели ISO 8601 (от 1 до 53).

Возвращает 0, если дата недействительна. В противном случае возвращает номер недели для даты. Если yearNumber не nullptr (по умолчанию), сохраняет год в *yearNumber.

В соответствии с ISO 8601, каждая неделя относится к году, к которому принадлежит большинство её дней, в григорианском календаре. Так как неделя ISO 8601 начинается с понедельника, это год, в котором четверг недели попадает. Большинство лет имеет 52 недели, но некоторые имеют 53.

Примечание: *yearNumber не всегда совпадает с year(). Например, 1 января 2000 года имеет номер недели 52 в году 1999, а 31 декабря 2002 года имеет номер недели 1 в году 2003.

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

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