Класс 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 могут и меняются регулярно, и могут варьироваться в зависимости от того, насколько недавно были обновлены данные хост-системы. Поэтому нельзя полагаться на существование конкретного идентификатора на любой хост-системе. Для определения доступных идентификаторов IANA необходимо использовать availableTimeZoneIds().

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

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

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

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

Поддержка часовых поясов Windows ограничена по сравнению со стандартной базой данных часовых поясов IANA. Часовые пояса 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 для получения стандартного времени в часовом поясе. Смещение летнего времени — это количество секунд, которое необходимо добавить к стандартному смещению времени для получения летнего времени (сокращенно ЛЕТ и иногда называемого «дневным временем» или «летним временем») в часовом поясе.

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

Лицензия

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

См. также QDateTime.

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

enum QTimeZone::NameType

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

typedef QTimeZone::OffsetDataList

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

enum QTimeZone::TimeType

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

enum QTimeZone::anonymous

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

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

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 в этот объект.

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 , если системный бэкенд поддерживает получение переходов.

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

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

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

Возвращает эквивалент идентификатора Windows, соответствующий заданному ianaId.

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

QByteArray QTimeZone::id() const

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

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

Например, для часового пояса «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 этот идентификатор преобразуется из 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 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 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.

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

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

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

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

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

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