Класс QTimeZone

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

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

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

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

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

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

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

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

Этот класс предоставляет бессостояниеный вычислитель для преобразований между 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 TZ. Часовые пояса Windows охватывают более крупные географические области и, следовательно, менее точны при преобразованиях. Они также не поддерживают такое же количество исторических данных преобразований, поэтому могут быть точными только для текущего года.

QTimeZone использует таблицу преобразований, полученную из данных Unicode CLDR, для сопоставления между идентификаторами 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 и иногда называемое «летним временем» или «летним временем») в часовом поясе.

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

Лицензия

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

См. также QDateTime.

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

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

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

тип QTimeZone::OffsetDataList

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

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

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

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

QTimeZone::QTimeZone()

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

QTimeZone::QTimeZone(const QByteArray &ianaId)

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

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

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

QTimeZone::QTimeZone(int offsetSeconds)

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

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

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(const QTimeZone &other)

Конструктор копирования, копирует other в this.

QTimeZone::~QTimeZone()

Уничтожает часовой пояс.

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

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

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

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

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().

bool QTimeZone::hasDaylightTime() const

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

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

bool QTimeZone::hasTransitions() const

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

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

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

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

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

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

QByteArray QTimeZone::id() const

Возвращает идентификатор IANA для часового пояса.

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

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 если этот часовой пояс действителен.

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

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

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

Заданное afterDateTime исключается.

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

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().

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".

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 ID может охватывать несколько IANA ID в разных странах, эта функция возвращает наиболее часто используемый IANA ID без учета страны и поэтому должна использоваться с осторожностью. Обычно лучше запрашивать стандарт для конкретной страны.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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