Класс QTime

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

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

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

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

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

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

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

Объект QTime содержит время, которое он может выразить как количество часов, минут, секунд и миллисекунд с момента полуночи. Он предоставляет функции для сравнения времен и для изменения времени на заданное количество миллисекунд.

QTime использует 24-часовой формат; он не имеет понятия AM/PM. В отличие от QDateTime, QTime ничего не знает о часовых поясах или летнем времени.

Объект QTime обычно создается либо путем явного указания количества часов, минут, секунд и миллисекунд, либо с помощью статической функции currentTime(), которая создает объект QTime, представляющий местное время системы.

Функции hour(), minute(), second() и msec() предоставляют доступ к количеству часов, минут, секунд и миллисекунд времени. Та же информация предоставляется в текстовом формате функцией toString().

Функции addSecs() и addMSecs() предоставляют время на заданное количество секунд или миллисекунд позже, чем заданное время. Соответственно, количество секунд или миллисекунд между двумя временами можно найти с помощью secsTo() или msecsTo().

QTime предоставляет полный набор операторов для сравнения двух объектов QTime; более раннее время считается меньшим, чем более позднее; если A.msecsTo(B) положительно, то A < B.

См. также QDate и QDateTime.

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

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

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

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

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

Примеры форматов строк (предполагая, что QTime составляет 14:13:09.042, а системный язык — en_US)

Если время недействительно, возвращается пустая строка. Если format пуста, используется форма по умолчанию "hh:mm:ss".

Примечание: Если требуются локализованные формы am или pm (форматы AP, ap, A или a), необходимо переключиться на использование QLocale::system().toString() в качестве методов QTime; методы в Qt 6 изменятся на использование английского языка (C locale).

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

QTime::QTime(int h, int m, int s = 0, int ms = 0)

Создаёт время с часами h, минутами m, секундами s и миллисекундами ms.

h должно быть в диапазоне от 0 до 23, m и s должны быть в диапазоне от 0 до 59, а ms должно быть в диапазоне от 0 до 999.

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

QTime::QTime()

Создаёт объект времени по умолчанию. Для нулевого времени isNull() возвращает true, а isValid() возвращает false. Если вам нужно время 0, используйте QTime(0, 0). Для начала дня см. QDate::startOfDay().

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

QTime QTime::addMSecs(int ms) const

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

Обратите внимание, что время перейдёт к следующему дню, если оно пересечёт полночь. См. addSecs() для примера.

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

См. также addSecs(), msecsTo() и QDateTime::addMSecs().

QTime QTime::addSecs(int s) const

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

Обратите внимание, что время перейдёт к следующему дню, если оно пересечёт полночь.

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

Пример:

QTime n(14, 0, 0);                // n == 14:00:00
QTime t;
t = n.addSecs(70);                // t == 14:01:10
t = n.addSecs(-70);               // t == 13:58:50
t = n.addSecs(10 * 60 * 60 + 5);  // t == 00:00:05
t = n.addSecs(-15 * 60 * 60);     // t == 23:00:00

См. также addMSecs(), secsTo() и QDateTime::addSecs().

[static] QTime QTime::currentTime()

Возвращает текущее время, полученное с системных часов.

Обратите внимание, что точность зависит от точности базовой операционной системы; не все системы обеспечивают точность до 1 миллисекунды.

Кроме того, currentTime() увеличивается только в течение каждого дня; оно уменьшается на 24 часа каждый раз, когда проходит полночь; и, кроме этого, изменения в нём могут не соответствовать прошедшему времени, если произойдёт переход на летнее время.

См. также QDateTime::currentDateTime() и QDateTime::currentDateTimeUtc().

int QTime::elapsed() const

Возвращает количество миллисекунд, прошедших с момента последнего вызова start() или restart().

Обратите внимание, что счётчик обнуляется через 24 часа после последнего вызова start() или restart().

Обратите внимание, что точность зависит от точности базовой операционной системы; не все системы обеспечивают точность до 1 миллисекунды.

Предупреждение: Если системные настройки часов были изменены с момента последнего вызова start() или restart(), результат является неопределённым. Это может произойти при включении или выключении летнего времени.

См. также start() и restart().

[static] QTime QTime::fromMSecsSinceStartOfDay(int msecs)

Возвращает новый экземпляр QTime со временем, установленным в количестве msecs миллисекунд с начала дня, то есть с 00:00:00.

Если msecs выходит за допустимый диапазон, возвращается недействительное время QTime.

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

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

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

Обратите внимание, что fromString() использует строку, закодированную в формате "C", для преобразования миллисекунд в число с плавающей точкой. Если системный язык не "C", это может привести к двум попыткам преобразования (если преобразование не удалось для системного языка по умолчанию). Это следует рассматривать как реализационное свойство.

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

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

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

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

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

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

QTime time = QTime::fromString("1mm12car00", "m'mm'hcarss");
// time is 12:01.00

Если формат не удовлетворён, возвращается недействительное время QTime. Выражения, которые не ожидают ведущих нулей (h, m, s и z), жадные. Это означает, что они будут использовать два знака, даже если это выведет их за пределы допустимого диапазона и оставит слишком мало знаков для других разделов. Например, следующая строка могла означать 00:07:10, но m захватит два знака, в результате чего время станет недействительным:

QTime time = QTime::fromString("00:710", "hh:ms"); // invalid

Любой раздел, который не представлен в формате, будет установлен в ноль. Например:

QTime time = QTime::fromString("1.30", "m.s");
// time is 00:01:30.000

Примечание: Если используются локализованные формы am или pm (форматы AP, ap, A или a), необходимо переключиться на использование QLocale::system().toTime(), поскольку методы QTime в Qt 6 будут распознавать только английский язык (C locale).

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

int QTime::hour() const

Возвращает часть часа (0 до 23) времени.

Возвращает -1, если время недействительно.

См. также minute(), second() и msec().

bool QTime::isNull() const

Возвращает true, если время равно нулю (то есть объект QTime был создан с помощью конструктора по умолчанию); в противном случае возвращает false. Нулевое время также является недействительным временем.

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

bool QTime::isValid() const

Возвращает true если время валидно; в противном случае возвращает false. Например, время 23:30:55.746 валидно, а 24:12:30 — нет.

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

[static] bool QTime::isValid(int h, int m, int s, int ms = 0)

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

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

Время валидно, если h находится в диапазоне от 0 до 23, m и s — в диапазоне от 0 до 59, а ms — в диапазоне от 0 до 999.

Пример:

QTime::isValid(21, 10, 30); // returns true
QTime::isValid(22, 5,  62); // returns false

int QTime::minute() const

Возвращает минутную часть (0–59) времени.

Возвращает -1, если время невалидно.

См. также hour(), second() и msec().

int QTime::msec() const

Возвращает миллисекундную часть (0–999) времени.

Возвращает -1, если время невалидно.

См. также hour(), minute() и second().

int QTime::msecsSinceStartOfDay() const

Возвращает количество миллисекунд с начала дня, т.е. с 00:00:00.

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

int QTime::msecsTo(const QTime &t) const

Возвращает количество миллисекунд от текущего времени до времени t. Если t раньше текущего времени, возвращается отрицательное значение.

Поскольку QTime измеряет время в течение одного дня, а в сутках 86400 секунд, результат всегда находится в диапазоне от -86400000 до 86400000 мс.

Возвращает 0, если одно из времён невалидно.

См. также secsTo(), addMSecs() и QDateTime::msecsTo().

int QTime::restart()

Устанавливает текущее время и возвращает количество миллисекунд, прошедших с момента последнего вызова start() или restart().

Этот метод гарантированно атомен, что делает его удобным для повторных измерений. Вызовите start() для начала первого измерения и restart() для каждого последующего.

Обратите внимание, что счётчик обнуляется через 24 часа после последнего вызова start() или restart().

Предупреждение: Если настройки системных часов изменились с момента последнего вызова start() или restart(), результат будет неопределённым. Это может произойти при переходе на/с летнего времени.

См. также start(), elapsed() и currentTime().

int QTime::second() const

Возвращает секунды (0–59) времени.

Возвращает -1, если время невалидно.

См. также hour(), minute() и msec().

int QTime::secsTo(const QTime &t) const

Возвращает количество секунд от текущего времени до времени t. Если t раньше текущего времени, возвращается отрицательное значение.

Поскольку QTime измеряет время в течение одного дня, а в сутках 86400 секунд, результат всегда находится в диапазоне от -86400 до 86400.

secsTo() не учитывает миллисекунды.

Возвращает 0, если одно из времён невалидно.

См. также addSecs() и QDateTime::secsTo().

bool QTime::setHMS(int h, int m, int s, int ms = 0)

Устанавливает время по часам h, минутам m, секундам s и миллисекундам ms.

h должен быть в диапазоне от 0 до 23, m и s — от 0 до 59, а ms — от 0 до 999. Возвращает true если установленное время валидно; в противном случае возвращает false.

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

void QTime::start()

Устанавливает текущее время. Это удобно для измерения времени:

QTime t;
t.start();
some_lengthy_task();
qDebug("Time elapsed: %d ms", t.elapsed());

См. также restart(), elapsed() и currentTime().

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

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

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

Если format равен Qt::TextDate, формат строки — ЧЧ:мм:сс; например, 1 секунда до полуночи будет "23:59:59".

Если format равен Qt::ISODate, формат строки соответствует расширенному спецификации ISO 8601 для представления дат, представленному как ЧЧ:мм:сс. Для включения миллисекунд в дату ISO 8601 используйте формат Qt::ISODateWithMs, который соответствует ЧЧ:мм:сс.zzz.

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

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

Если format равен Qt::RFC2822Date, строка форматируется в формате, совместимом с RFC 2822. Пример такого форматирования: "23:59:20".

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

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

bool QTime::operator!=(const QTime &t) const

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

bool QTime::operator<(const QTime &t) const

Возвращает true если текущее время раньше t; в противном случае возвращает false.

bool QTime::operator<=(const QTime &t) const

Возвращает true если текущее время раньше или равно t; в противном случае возвращает false.

bool QTime::operator==(const QTime &t) const

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

bool QTime::operator>(const QTime &t) const

Возвращает true если текущее время позже t; в противном случае возвращает false.

bool QTime::operator>=(const QTime &t) const

Возвращает true если текущее время позже или равно t; в противном случае возвращает false.