Timezone

Arduino library to support local/UTC time conversions using rules

See SystemClock NTP for example usage.

Port of https://github.com/JChristensen/Timezone for Sming.

API Documentation

class Timezone

Class to support local/UTC time conversions using rules.

Public Functions

time_t toLocal(time_t utc, const TimeChangeRule **p_tcr = nullptr)

Convert the given UTC time to local time, standard or daylight time.

Parameters
  • utc – Time in UTC

  • p_tcr – Optionally return the rule used to convert the time

Returns

time_t – The local time

time_t toUTC(time_t local)

Convert the given local time to UTC time.

WARNING: This function is provided for completeness, but should seldom be needed and should be used sparingly and carefully.

Ambiguous situations occur after the Standard-to-DST and the DST-to-Standard time transitions. When changing to DST, there is one hour of local time that does not exist, since the clock moves forward one hour. Similarly, when changing to standard time, there is one hour of local times that occur twice since the clock moves back one hour.

This function does not test whether it is passed an erroneous time value during the Local -> DST transition that does not exist. If passed such a time, an incorrect UTC time value will be returned.

If passed a local time value during the DST -> Local transition that occurs twice, it will be treated as the earlier time, i.e. the time that occurs before the transition.

Calling this function with local times during a transition interval should be avoided.

Note

Parameters

local – Local time

Returns

time_t – Time in UTC

bool utcIsDST(time_t utc)

Determine whether the UTC time is within the DST interval or the Standard time interval.

Parameters

utc

Returns

bool – true if time is within DST

bool locIsDST(time_t local)

Determine whether the given local time is within the DST interval or the Standard time interval.

Parameters

local – Local time

Returns

bool – true if time is within DST

inline const char *timeTag(bool isDst) const

Return the appropriate dalight-savings tag to append to displayed times.

Parameters

isDst – true if DST tag is required, otherwise non-DST tag is returned

Returns

const – char* The tag

inline const char *utcTimeTag(time_t utc)

Return the appropriate time tag for a UTC time.

Parameters

utc – The time in UTC

Returns

const – char* Tag, such as UTC, BST, etc.

inline const char *localTimeTag(time_t local)

Return the appropriate time tag for a local time.

Parameters

local – The local time

Returns

const – char* Tag, such as UTC, BST, etc.

struct TimeChangeRule

Public Members

char tag[6]

e.g. DST, UTC, etc.

week_t week

First, Second, Third, Fourth, or Last week of the month.

dow_t dow

Day of week, 0=Sun.

month_t month

1=Jan

uint8_t hour

0-23

int offset

Offset from UTC in minutes.

enum week_t

Values:

enumerator Last
enumerator First
enumerator Second
enumerator Third
enumerator Fourth
enum dow_t

Values:

enumerator Sun
enumerator Mon
enumerator Tue
enumerator Wed
enumerator Thu
enumerator Fri
enumerator Sat
enum month_t

Values:

enumerator Jan
enumerator Feb
enumerator Mar
enumerator Apr
enumerator May
enumerator Jun
enumerator Jul
enumerator Aug
enumerator Sep
enumerator Oct
enumerator Nov
enumerator Dec

References

Used by

SoC support

  • esp32

  • esp32c3

  • esp32s2

  • esp32s3

  • esp8266

  • host

  • rp2040