Класс QTimeZone

Класс QTimeZone преобразует время между UTC и местным временем в определённой часовой зоне. Подробнее...

Этот класс был представлен в Qt 5.2.

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

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

Публичные типы

Общие функции

Статические публичные члены

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

Этот класс предоставляет бессостоятельный калькулятор для преобразования временных зон между UTC и локальным временем в определенной временной зоне. По умолчанию он использует данные о часовых поясах хост-системы для выполнения этих преобразований.

Этот класс предназначен в первую очередь для использования с QDateTime; большинство приложений не нуждаются в прямом доступе к этому классу и должны вместо этого использовать QDateTime с Qt::TimeSpec типа Qt::TimeZone.

Примечание: Для согласованности с QDateTime, QTimeZone не учитывает високосные секунды.

Примечания

Идентификаторы часовых поясов IANA

QTimeZone использует идентификаторы часовых поясов IANA, определённые в базе данных часовых поясов IANA (http://www.iana.org/time-zones). Это обеспечивает стандартный идентификатор на всех поддерживаемых платформах. Большинство платформ поддерживают идентификаторы IANA и базу данных IANA напрямую, но для Windows требуется сопоставление с родными идентификаторами. Более подробную информацию см. ниже.

Идентификаторы IANA могут и меняются регулярно и могут отличаться в зависимости от того, когда данные были обновлены на хостовой системе. Поэтому нельзя полагаться на существование определённого идентификатора на любой хостовой системе. Вы должны использовать availableTimeZoneIds() для определения доступных идентификаторов IANA.

Идентификаторы и база данных IANA также известны как идентификаторы и база данных Olson, названные в честь их создателя.

Часовые пояса с смещением от UTC

Предоставляется фоновый процесс для часового пояса UTC по умолчанию, который всегда гарантированно доступен. Он предоставляет набор общих часовых поясов со смещением от UTC в диапазоне от UTC-14:00 до UTC+14:00. Эти часовые пояса можно создать, используя стандартные имена формата ISO «UTC+00:00», как перечислены в availableTimeZoneIds(), или используя количество секунд смещения.

Часовые пояса Windows

Поддержка часовых поясов в Windows сильно ограничена по сравнению со стандартной базой данных часовых поясов IANA. Часовые пояса Windows охватывают более крупные географические области и поэтому менее точны при преобразованиях. Они также не поддерживают такое количество исторических данных преобразования, поэтому могут быть точными только для текущего года.

QTimeZone использует таблицу преобразования, полученную из данных CLDR Unicode, для сопоставления между идентификаторами IANA и идентификаторами Windows. В зависимости от вашей версии Windows и Qt, эта таблица может не предоставить допустимого преобразования, в результате чего будет возвращено «UTC».

QTimeZone предоставляет общедоступный API для использования этой таблицы преобразования. Идентификатор Windows, используемый, является ключом реестра Windows для часового пояса, который также является идентификатором MS Exchange EWS, но отличается от имени часового пояса (TZID) и кода COD, используемых MS Exchange в версиях до 2007 года.

Системный часовой пояс

QTimeZone не поддерживает никакого понятия системного или по умолчанию часового пояса. Если вам требуется QDateTime, использующий текущий системный часовой пояс в любой момент, используйте Qt::TimeSpec типа Qt::LocalTime.

Метод systemTimeZoneId() возвращает текущий системный идентификатор часового пояса IANA, который на системах Unix всегда будет правильным. В Windows этот идентификатор преобразуется из системного идентификатора Windows с использованием внутренней таблицы преобразования и выбранной пользователем страны. Вследствие этого есть небольшая вероятность, что в любой установке Windows могут быть идентификаторы, неизвестные Qt, в этом случае будет возвращено «UTC».

Создание нового экземпляра QTimeZone с использованием системного идентификатора часового пояса создаст только неизменяемую копию часового пояса; она не изменится, если системный часовой пояс изменится.

Смещения часовых поясов

Разница между UTC и местным временем в часовом поясе выражается как смещение в секундах от UTC, т.е. количество секунд, которое нужно добавить к UTC для получения местного времени. Общее смещение состоит из двух компонентов: стандартного смещения и смещения летнего времени. Стандартное смещение — это количество секунд, которое нужно добавить к UTC для получения стандартного времени в часовом поясе. Смещение летнего времени — это количество секунд, которое нужно добавить к стандартному смещению для получения летнего времени (сокращённо DST, иногда называемого «летним временем» или «летним временем») в часовом поясе.

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

Лицензия

Этот класс содержит данные, полученные из файлов данных CLDR, в соответствии с условиями лицензии на файлы и программное обеспечение Unicode. Подробную информацию см. на странице Unicode Common Locale Data Repository (CLDR).

См. также QDateTime.

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

перечисление QTimeZone::NameType

Тип имени часового пояса.

тип QTimeZone::OffsetDataList

Синоним для QVector<OffsetData>.

перечисление QTimeZone::TimeType

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

перечисление QTimeZone::anonymous

Здоровые смещения UTC находятся в диапазоне от -14 до +14 часов. Известный часовой пояс > 12 часов к западу от Гринвича (остров Бейкер, США). Известный часовой пояс > 14 часов к востоку от Гринвича (Киритимати, остров Рождества, Кирибати).

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

QTimeZone::QTimeZone(const QTimeZone &other)

Конструктор копирования, копирует other в этот экземпляр.

QTimeZone::QTimeZone(const QByteArray &ianaId, int offsetSeconds, const QString &name, const QString &abbreviation, QLocale::Country country = QLocale::AnyCountry, const QString &comment = QString())

Создаёт пользовательский часовой пояс с идентификатором ianaId и смещением от UTC offsetSeconds. Свойство name будет именем, используемым displayName() для LongName, свойство abbreviation будет использоваться displayName() для ShortName и abbreviation(), а необязательное свойство country будет использоваться country(). Свойство comment — это необязательная заметка, которая может быть отображена в графическом интерфейсе для помощи пользователям в выборе часового пояса.

Свойство ianaId не должно быть одним из доступных системных идентификаторов, возвращаемых availableTimeZoneIds(). Свойство offsetSeconds от UTC должно быть в диапазоне от -14 до +14 часов.

Если у пользовательского часового пояса нет конкретной страны, она устанавливается по умолчанию в QLocale::AnyCountry.

QTimeZone::QTimeZone(int offsetSeconds)

Создаёт экземпляр часового пояса с указанным смещением от UTC offsetSeconds.

Свойство offsetSeconds от UTC должно быть в диапазоне от -14 до +14 часов, в противном случае будет возвращён недопустимый часовой пояс.

QTimeZone::QTimeZone(const QByteArray &ianaId)

Создаёт экземпляр запрошенного часового пояса ianaId.

Идентификатор должен быть одним из доступных системных идентификаторов или допустимым идентификатором UTC со смещением, в противном случае будет возвращён недопустимый часовой пояс.

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

QTimeZone::QTimeZone()

Создаёт экземпляр пустого/недопустимого часового пояса.

QTimeZone &QTimeZone::operator=(QTimeZone &&other)

Оператор перемещения присваивает other этому экземпляру QTimeZone, передавая владение управляемым указателем этому экземпляру.

QTimeZone &QTimeZone::operator=(const QTimeZone &other)

Оператор присваивания, присваивает other этому экземпляру.

QTimeZone::~QTimeZone()

Удаляет часовой пояс.

QString QTimeZone::abbreviation(const QDateTime &atDateTime) const

Возвращает аббревиатуру часового пояса в заданный момент времени atDateTime. Аббревиатура может изменяться в зависимости от летнего времени или исторических событий.

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

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

[static] QList<QByteArray> QTimeZone::availableTimeZoneIds()

Возвращает список всех доступных идентификаторов часовых поясов IANA в этой системе.

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

[static] QList<QByteArray> QTimeZone::availableTimeZoneIds(QLocale::Country country)

Возвращает список всех доступных идентификаторов часовых поясов IANA для заданной страны country.

В качестве специального случая, country типа Qt::AnyCountry возвращает часовые пояса, не связанные с какой-либо страной, например, UTC. Если вам нужен список всех идентификаторов часовых поясов для всех стран, используйте стандартный метод availableTimeZoneIds().

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

[static] QList<QByteArray> QTimeZone::availableTimeZoneIds(int offsetSeconds)

Возвращает список всех доступных идентификаторов часовых поясов IANA с заданным стандартным смещением по времени offsetSeconds.

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

QString QTimeZone::comment() const

Возвращает комментарий к часовому поясу.

Комментарий может быть предоставлен хост-платформой для помощи пользователям в выборе правильного часового пояса. В зависимости от платформы он может не быть локализован.

QLocale::Country QTimeZone::country() const

Возвращает страну часового пояса.

int QTimeZone::daylightTimeOffset(const QDateTime &atDateTime) const

Возвращает смещение летнего времени в заданный момент времени atDateTime, т.е. количество секунд, которое нужно добавить к стандартному смещению, чтобы получить местное смещение летнего времени.

Например, для часового пояса «Europe/Berlin» смещение летнего времени составляет +3600 секунд. В стандартное время daylightTimeOffset() вернёт 0, а когда летнее время в силе, оно вернёт +3600.

См. также offsetFromUtc() и standardTimeOffset().

QString QTimeZone::displayName(const QDateTime &atDateTime, QTimeZone::NameType nameType = QTimeZone::DefaultName, const QLocale &locale = QLocale()) const

Возвращает локализованное отображаемое имя часового пояса в заданный момент времени atDateTime для заданного типа имени nameType в заданном locale. Запрашиваемые nameType и locale могут не поддерживаться на всех платформах, в этом случае будет возвращён лучший доступный вариант.

Если locale не указан, будет использован локаль по умолчанию приложения.

Имя может изменяться в зависимости от летнего времени или исторических событий.

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

QString QTimeZone::displayName(QTimeZone::TimeType timeType, QTimeZone::NameType nameType = QTimeZone::DefaultName, const QLocale &locale = QLocale()) const

Возвращает локализованное отображаемое имя часового пояса для заданного timeType и nameType в заданном locale. Запрашиваемые nameType и locale могут не поддерживаться на всех платформах, в этом случае будет возвращён лучший доступный вариант.

Если locale не указан, будет использован локаль по умолчанию приложения.

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

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

[static] QTimeZone QTimeZone::fromCFTimeZone(CFTimeZoneRef timeZone)

Создаёт новый QTimeZone, содержащий копию CFTimeZone timeZone.

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

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

[static] QTimeZone QTimeZone::fromNSTimeZone(const NSTimeZone *timeZone)

Создаёт новый QTimeZone, содержащий копию NSTimeZone timeZone.

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

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

bool QTimeZone::hasDaylightTime() const

Возвращает true если часовой пояс когда-либо использовал летнее время.

См. также isDaylightTime() и daylightTimeOffset().

bool QTimeZone::hasTransitions() const

Возвращает true если системный бэкенд поддерживает получение переходов.

Переходы — это изменения в часовом поясе: они происходят, когда DST включается или выключается, и когда власти изменяют смещения для часового пояса.

См. также nextTransition(), previousTransition() и transitions().

[static] QByteArray QTimeZone::ianaIdToWindowsId(const QByteArray &ianaId)

Возвращает эквивалент идентификатора Windows для данного ianaId.

См. также windowsIdToDefaultIanaId() и windowsIdToIanaIds().

QByteArray QTimeZone::id() const

Возвращает IANA ID для часового пояса.

IANA ID используются на всех платформах. В Windows они переводятся из идентификатора Windows в ближайший IANA ID для часового пояса и страны.

bool QTimeZone::isDaylightTime(const QDateTime &atDateTime) const

Возвращает true если летнее время действовало в заданный момент времени atDateTime.

См. также hasDaylightTime() и daylightTimeOffset().

[static] bool QTimeZone::isTimeZoneIdAvailable(const QByteArray &ianaId)

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

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

bool QTimeZone::isValid() const

Возвращает true если часовой пояс действителен.

QTimeZone::OffsetData QTimeZone::nextTransition(const QDateTime &afterDateTime) const

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

Если перехода после заданного afterDateTime нет, возвращается недействительный OffsetData с недействительным QDateTime.

Заданный afterDateTime исключён.

См. также hasTransitions(), previousTransition() и transitions().

QTimeZone::OffsetData QTimeZone::offsetData(const QDateTime &forDateTime) const

Возвращает эффективные детали смещения в заданный момент времени forDateTime. Это эквивалентно вызову offsetFromUtc(), abbreviation() и т.д. по отдельности, но более эффективно.

См. также offsetFromUtc(), standardTimeOffset(), daylightTimeOffset() и abbreviation().

int QTimeZone::offsetFromUtc(const QDateTime &atDateTime) const

Возвращает общее эффективное смещение в заданный момент времени atDateTime, т.е. количество секунд, которое нужно добавить к UTC, чтобы получить местное время. Это включает в себя любое смещение летнего времени, которое может действовать, т.е. это сумма standardTimeOffset() и daylightTimeOffset() для данного момента времени.

Например, для часового пояса "Europe/Berlin" стандартное смещение по времени составляет +3600 секунд, а смещение по времени летнего времени — +3600 секунд. Во время стандартного времени offsetFromUtc() вернёт +3600 (UTC+01:00), а во время летнего времени — +7200 (UTC+02:00).

См. также standardTimeOffset() и daylightTimeOffset().

QTimeZone::OffsetData QTimeZone::previousTransition(const QDateTime &beforeDateTime) const

Возвращает первое изменение часового пояса до заданного beforeDateTime. Это наиболее полезно, когда у вас есть временная точка перехода и вы хотите найти переходы до неё.

Если нет перехода до заданного beforeDateTime, то возвращается недопустимый объект OffsetData с недопустимым QDateTime.

Заданное beforeDateTime не включается.

См. также hasTransitions(), nextTransition() и transitions().

int QTimeZone::standardTimeOffset(const QDateTime &atDateTime) const

Возвращает стандартное смещение времени в заданный момент atDateTime, т. е. количество секунд, которые нужно добавить к UTC, чтобы получить местное стандартное время. Это исключает любое смещение летнего времени, которое может быть в силе.

Например, для часового пояса "Europe/Berlin" стандартное смещение времени составляет +3600 секунд. В стандартном и летнем времени offsetFromUtc() вернёт +3600 (UTC+01:00).

См. также offsetFromUtc() и daylightTimeOffset().

void QTimeZone::swap(QTimeZone &other)

Меняет местами экземпляр часового пояса с other. Эта функция очень быстрая и никогда не терпит неудачу.

[static] QTimeZone QTimeZone::systemTimeZone()

Возвращает объект QTimeZone, который ссылается на местное системное время, как указано в systemTimeZoneId().

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

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

[static] QByteArray QTimeZone::systemTimeZoneId()

Возвращает текущий системный часовой пояс IANA ID.

В Windows этот ID преобразуется из Windows ID с использованием внутренней таблицы преобразования и выбранной страной пользователя. Вследствие этого существует небольшая вероятность, что в любой установке Windows могут быть ID, неизвестные Qt, в этом случае будет возвращено "UTC".

CFTimeZoneRef QTimeZone::toCFTimeZone() const

Создаёт CFTimeZone из QTimeZone. Вызывающая сторона владеет объектом CFTimeZone и отвечает за его освобождение.

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

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

NSTimeZone *QTimeZone::toNSTimeZone() const

Создаёт NSTimeZone из QTimeZone. Объект NSTimeZone автоматически освобождается.

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

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

QTimeZone::OffsetDataList QTimeZone::transitions(const QDateTime &fromDateTime, const QDateTime &toDateTime) const

Возвращает список всех изменений часового пояса между заданными датами.

Заданные fromDateTime и toDateTime включаются.

См. также hasTransitions(), nextTransition() и previousTransition().

[static] QTimeZone QTimeZone::utc()

Возвращает объект QTimeZone, который ссылается на UTC (Всемирное координированное время).

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

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

[static] QByteArray QTimeZone::windowsIdToDefaultIanaId(const QByteArray &windowsId)

Возвращает IANA ID по умолчанию для заданного windowsId.

Поскольку идентификатор Windows может охватывать несколько IANA ID в нескольких разных странах, эта функция возвращает наиболее часто используемый IANA ID, не учитывая страну, и поэтому следует использовать с осторожностью. Обычно лучше запросить значение по умолчанию для определённой страны.

См. также ianaIdToWindowsId() и windowsIdToIanaIds().

[static] QByteArray QTimeZone::windowsIdToDefaultIanaId(const QByteArray &windowsId, QLocale::Country country)

Возвращает IANA ID по умолчанию для заданного windowsId и country.

Поскольку идентификатор Windows может охватывать несколько IANA ID в данной стране, возвращается наиболее часто используемый IANA ID в этой стране.

В качестве специального случая, QLocale::AnyCountry возвращает значение по умолчанию для тех IANA ID, которые не привязаны к какой-либо конкретной стране.

См. также ianaIdToWindowsId() и windowsIdToIanaIds().

[static] QList<QByteArray> QTimeZone::windowsIdToIanaIds(const QByteArray &windowsId)

Возвращает все IANA ID для заданного windowsId.

Возвращаемый список отсортирован по алфавиту.

См. также ianaIdToWindowsId() и windowsIdToDefaultIanaId().

[static] QList<QByteArray> QTimeZone::windowsIdToIanaIds(const QByteArray &windowsId, QLocale::Country country)

Возвращает все IANA ID для заданного windowsId и country.

В качестве специального случая, QLocale::AnyCountry возвращает те IANA ID, которые не привязаны к какой-либо конкретной стране.

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

См. также ianaIdToWindowsId() и windowsIdToDefaultIanaId().

bool QTimeZone::operator!=(const QTimeZone &other) const

Возвращает true если этот часовой пояс не равен other часовому поясу.

bool QTimeZone::operator==(const QTimeZone &other) const

Возвращает true если этот часовой пояс равен other часовому поясу.