Класс QTimeZone

Класс 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. Часовые пояса 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 и иногда называемое «дневное время» или «летнее время») в часовом поясе.

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

Лицензия

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

См. также QDateTime.

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

enum QTimeZone::NameType

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

QTimeZone::OffsetDataList

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

enum QTimeZone::TimeType

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

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

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

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

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

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

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

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

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

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

[static, since 5.9] QTimeZone QTimeZone::fromCFTimeZone(CFTimeZoneRef timeZone)

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

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

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

[static, since 5.9] 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 для часового пояса.

Идентификаторы 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 если данный часовой пояс является корректным.

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, since 5.5] QTimeZone QTimeZone::systemTimeZone()

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

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

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

[static] QByteArray QTimeZone::systemTimeZoneId()

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

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

[since 5.9] CFTimeZoneRef QTimeZone::toCFTimeZone() const

Создает CFTimeZone из QTimeZone.

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

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

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

[since 5.9] 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, since 5.5] 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.