Класс QTimeZone

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

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

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

Типы публичного доступа

Функции публичного доступа

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

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

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

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

Примечания

Идентификаторы часовых поясов 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, чтобы получить стандартное время в часовом поясе. Смещение летнего времени — это количество секунд, которое нужно добавить к стандартному смещению, чтобы получить летнее время (сокращенно DST и иногда называемое «летним временем» или «летним временем») в часовом поясе.

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

Лицензия

Этот класс включает данные, полученные из файлов данных CLDR, в соответствии с условиями лицензии на файлы и программное обеспечение Unicode. Подробности см. в разделе Репозиторий общих данных локали CLDR (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 в this.

QTimeZone::QTimeZone(const QByteArray &ianaId, int offsetSeconds, const QString &name, const QString &abbreviation, QLocale::Territory territory = QLocale::AnyTerritory, const QString &comment = QString())

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

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

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

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::Territory territory)

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

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

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

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

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

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

QString QTimeZone::comment() 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, 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 ID с использованием внутренней таблицы преобразований и выбранной пользователем страны. В результате существует небольшая вероятность того, что в любой установке Windows могут быть ID, неизвестные Qt, в этом случае будет возвращено «UTC».

[since 6.2] QLocale::Territory QTimeZone::territory() const

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

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

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

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

[static] QByteArray QTimeZone::windowsIdToDefaultIanaId(const QByteArray &windowsId, QLocale::Territory territory)

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

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

В качестве специального случая QLocale::AnyTerritory возвращает стандартный 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::Territory territory)

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

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

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

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

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

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

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

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