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

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

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

Примечание: Имена дней и месяцев должны быть на английском языке (C locale). Если используются локализованные имена месяцев и дней, используйте 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, если дата является нулевой; иначе возвращает 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

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