Класс QDate

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

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

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

Открытые типы

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

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

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

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

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

Объект 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

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

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

перечисление QDate::MonthNameType

Это перечисление описывает типы строковых представлений, используемых для имени месяца.

Это перечисление было добавлено или изменено в Qt 4.5.

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

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

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

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

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

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

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

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

См. также 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(const 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"). Хотя локализованные имена месяцев также можно использовать в Qt 5, они зависят от настроек региональных параметров пользователя.

Примечание: Поддержка локализованных дат, включая параметры формата Qt::SystemLocaleDate, Qt::SystemLocaleShortDate, Qt::SystemLocaleLongDate, Qt::LocaleDate, Qt::DefaultLocaleShortDate и Qt::DefaultLocaleLongDate, будет удалена в Qt 6. Используйте QLocale::toDate() вместо этого.

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

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

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

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

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

Использует 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

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

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

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

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

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

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

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, строка форматируется стандартным способом. Имена дня и месяца будут локальными именами, используя системный язык, т.е. QLocale::system(). Пример такого форматирования — "Сб Май 20 1995".

Если format равен Qt::ISODate, формат строки соответствует расширенному спецификации ISO 8601 для представления дат и времени, имея вид yyyy-MM-dd, где yyyy — год, MM — месяц в году (от 01 до 12), а dd — день месяца (от 01 до 31).

Опции format Qt::SystemLocaleDate, Qt::SystemLocaleShortDate и Qt::SystemLocaleLongDate будут удалены в Qt 6. Их использование следует заменить на QLocale::system().toString(date, QLocale::ShortFormat) или QLocale::system().toString(date, QLocale::LongFormat).

Опции формата Qt::LocaleDate, Qt::DefaultLocaleShortDate и Qt::DefaultLocaleLongDate будут удалены в Qt 6. Их следует заменить на QLocale().toString(date, QLocale::ShortFormat) или QLocale().toString(date, QLocale::LongFormat).

Если формат равен 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

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

bool QDate::operator!=(const QDate &d) const

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

См. также operator==().

bool QDate::operator<(const QDate &d) const

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

bool QDate::operator<=(const QDate &d) const

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

bool QDate::operator==(const QDate &d) const

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

bool QDate::operator>(const QDate &d) const

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

bool QDate::operator>=(const QDate &d) const

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