Класс 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. Часовые пояса 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.

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

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

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

тип QTimeZone::OffsetDataList

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

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

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

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

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

QList<QByteArray> QTimeZone::availableTimeZoneIds()

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

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

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" смещение DST составляет +3600 секунд. Во время стандартного времени daylightTimeOffset() возвращает 0, а когда действует летнее время, оно возвращает +3600.

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

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

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

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

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

См. также 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 ID для заданного ianaId.

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

QByteArray QTimeZone::id() const

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

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

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, чтобы получить местное время. Это включает любое смещение DST, которое может быть в силе, т.е. это сумма standardTimeOffset() и daylightTimeOffset() для данной даты и времени.

Например, для часового пояса "Europe/Berlin" стандартное смещение составляет +3600 секунд, а смещение DST составляет +3600 секунд. Во время стандартного времени offsetFromUtc() вернет +3600 (UTC+01:00), а во время DST оно вернет +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, чтобы получить местное стандартное время. Это не включает любое смещение 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().

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.