Класс QDate

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

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

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

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

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

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

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

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

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

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

Функции year(), month() и day() предоставляют доступ к году, месяцу и дню. Также доступны функции dayOfWeek() и dayOfYear(). Та же информация представлена в текстовом формате функцией toString(). Номера дня и месяца могут быть сопоставлены с именами с помощью QLocale.

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

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

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

Примечания

Отсутствие года 0

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

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

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

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

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

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

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

Это перечисление описывает типы строкового представления имени месяца.

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

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

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

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

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

Форматы без разделителей (например, "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) или недействительного часового пояса как zone также приведет к недействительному результату, так же как и даты, выходящие за границы, представимые 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().

int QDate::day() const

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

int QDate::dayOfWeek(QCalendar cal) const

Возвращает день недели (1 = понедельник, 7 = воскресенье) для этой даты.

Использует cal в качестве календаря, если задано, иначе — григорианский календарь. Возвращает 0, если дата недействительна. Некоторые календари могут присваивать значениям больше 7 специальный смысл (например, для добавочных дней).

См. также day(), dayOfYear() и Qt::DayOfWeek.

int QDate::dayOfWeek() const

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

int QDate::dayOfYear(QCalendar cal) const

Возвращает день года (1 для первого дня) для этой даты.

Использует cal в качестве календаря, если задано, иначе — григорианский календарь. Возвращает 0, если либо дата, либо первый день года недействительны.

См. также day() и dayOfWeek().

int QDate::dayOfYear() const

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

int QDate::daysInMonth(QCalendar cal) const

Возвращает количество дней в месяце для этой даты.

Использует cal в качестве календаря, если задано, иначе — григорианский календарь (в котором результат колеблется от 28 до 31). Возвращает 0, если дата недействительна.

См. также day() и daysInYear().

int QDate::daysInMonth() const

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

int QDate::daysInYear(QCalendar cal) const

Возвращает количество дней в году для этой даты.

Использует cal в качестве календаря, если задано, иначе — григорианский календарь (в котором результат 365 или 366). Возвращает 0, если дата недействительна.

См. также day() и daysInMonth().

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

Примечание для Qt::TextDate: Рекомендуется использовать английские сокращенные названия месяцев (например, "Янв"). Хотя можно использовать и локальные названия месяцев, они зависят от настроек языка пользователя.

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

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

void QDate::getDate(int *year, int *month, int *day) const

Извлекает год, месяц и день даты и присваивает их *year, *month и *day. Указатели могут быть null.

Возвращает 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 если дата равна null; в противном случае возвращает false. Дата null считается недействительной.

Примечание: Поведение этой функции эквивалентно 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().

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(). Пример такого форматирования: "Sat May 20 1995".

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

Если format равен Qt::SystemLocaleShortDate или Qt::SystemLocaleLongDate, формат строки зависит от настроек локали системы. Идентично вызову QLocale::system().toString(date, QLocale::ShortFormat) или QLocale::system().toString(date, QLocale::LongFormat).

Если format равен Qt::DefaultLocaleShortDate или Qt::DefaultLocaleLongDate, формат строки зависит от локальной настройки приложения по умолчанию. Это локаль, установленная с помощью QLocale::setDefault(), или системная локаль, если локаль по умолчанию не установлена. Идентично вызову QLocale().toString(date, QLocale::ShortFormat) или QLocale().toString(date, QLocale::LongFormat).

Если format равен Qt::RFC2822Date, строка форматируется совместимо со спецификацией RFC 2822. Пример такого форматирования: "20 May 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().

int QDate::year() const

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

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.

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

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