Class to support local/UTC time conversions using rules. More...

#include <Timezone.h>

Public Member Functions
	Timezone ()

	Timezone (const Rule &dstStart, const Rule &stdStart)
	Create a timezone with daylight savings. More...

	Timezone (const Rule &std)
	Create a timezone which has no daylight savings. More...

void	init (const Rule &dstStart, const Rule &stdStart)

	operator bool () const

time_t	toLocal (time_t utc, const Rule **rule=nullptr)
	Convert the given UTC time to local time, standard or daylight time. More...

ZonedTime	makeZoned (time_t utc, bool beforeTransition=false)
	Obtain a ZonedTime instance for the given UTC. More...

ZonedTime	toUTC (time_t local)
	Convert the given local time to UTC time. More...

bool	utcIsDST (time_t utc)
	Determine whether the UTC time is within the DST interval or the Standard time interval. More...

bool	locIsDST (time_t local)
	Determine whether the given local time is within the DST interval or the Standard time interval. More...

const char *	timeTag (bool isDst) const
	Return the appropriate dalight-savings tag to append to displayed times. More...

const char *	utcTimeTag (time_t utc)
	Return the appropriate time tag for a UTC time. More...

const char *	localTimeTag (time_t local)
	Return the appropriate time tag for a local time. More...

ZonedTime	getNextChange (time_t utcFrom)
	Determine when the next change to/from DST is. More...

ZonedTime	getTransition (uint16_t year, bool toDst)
	Get transition time for the given year. More...

const Rule &	getRule (bool isDst) const
	Get reference to a timechange rule. More...

bool	hasDaylightSavings () const
	If dst and std rules are the same we do not use daylight savings. More...

String	toString () const

size_t	printTo (Print &p) const

Static Public Member Functions
Construct a Timezone from a POSIX rule string
static Timezone	fromPosix (const char *tzstr)

static Timezone	fromPosix (const String &tzstr)

Detailed Description

Class to support local/UTC time conversions using rules.

Constructor & Destructor Documentation

◆ Timezone() [1/3]

TZ::Timezone::Timezone ( )

inline

◆ Timezone() [2/3]

TZ::Timezone::Timezone	(	const Rule &	dstStart,
		const Rule &	stdStart
	)

inline

Create a timezone with daylight savings.

Parameters

dstStart	Rule giving start of daylight savings
stdStart	Rule giving start of standard time

Note: If both rules are the same then the zone operates in permanent standard time

◆ Timezone() [3/3]

TZ::Timezone::Timezone ( const Rule & std )

inlineexplicit

Create a timezone which has no daylight savings.

Parameters

std	Rule describing standard time

Note: Only tag and offset fields from rule are significant

Member Function Documentation

◆ fromPosix() [1/2]

static Timezone TZ::Timezone::fromPosix ( const char * tzstr )

static

◆ fromPosix() [2/2]

static Timezone TZ::Timezone::fromPosix ( const String & tzstr )

inlinestatic

◆ getNextChange()

ZonedTime TZ::Timezone::getNextChange ( time_t utcFrom )

Determine when the next change to/from DST is.

Parameters

utcFrom Point in time after which change is to occur

Return values

ZonedTime UTC time When the change will occur, or maxTime if there is no DST in effect. ZonedTime::local() returns the new local time at the transition.

◆ getRule()

const Rule& TZ::Timezone::getRule ( bool isDst ) const

inline

Get reference to a timechange rule.

Parameters

isDst true for DST rule, false for STD rule

Return values

Rule

◆ getTransition()

ZonedTime TZ::Timezone::getTransition	(	uint16_t	year,
		bool	toDst
	)

Get transition time for the given year.

Parameters

year
toDst	true to obtain STD->DST transition, false for DST->STD

Return values

ZonedTime Time of transition, or maxTime if there is no DST in effect. ZonedTime::local() returns the new local time at the transition.

◆ hasDaylightSavings()

bool TZ::Timezone::hasDaylightSavings ( ) const

inline

If dst and std rules are the same we do not use daylight savings.

◆ init()

void TZ::Timezone::init	(	const Rule &	dstStart,
		const Rule &	stdStart
	)

inline

@deprected Use copy assignment, e.g. tz = Timezone(...)

◆ localTimeTag()

const char* TZ::Timezone::localTimeTag ( time_t local )

inline

Return the appropriate time tag for a local time.

Parameters

local The local time

Return values

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

◆ locIsDST()

bool TZ::Timezone::locIsDST ( time_t local )

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

Parameters

local Local time

Return values

bool	true if time is within DST

◆ makeZoned()

ZonedTime TZ::Timezone::makeZoned	(	time_t	utc,
		bool	beforeTransition = `false`
	)

Obtain a ZonedTime instance for the given UTC.

Parameters

utc	Time in UTC
beforeTransition	If time is exactly on a transition to/from daylight savings then this determines whether the returned information contains the local time prior to the change or after the change.

Return values

ZonedTime Contains the UTC time given plus offset, etc. at that point in time

◆ operator bool()

TZ::Timezone::operator bool ( ) const

inlineexplicit

◆ printTo()

size_t TZ::Timezone::printTo ( Print & p ) const

◆ timeTag()

const char* TZ::Timezone::timeTag ( bool isDst ) const

inline

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

Return values

const char* The tag

◆ toLocal()

time_t TZ::Timezone::toLocal	(	time_t	utc,
		const Rule **	rule = `nullptr`
	)

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

Parameters

utc	Time in UTC
rule	Optionally return the rule used to convert the time

Return values

time_t The local time

◆ toString()

String TZ::Timezone::toString ( ) const

◆ toUTC()

ZonedTime TZ::Timezone::toUTC ( time_t local )

Convert the given local time to UTC time.

Parameters

local Local time

Return values

ZonedTime Contains UTC point in time with associated local offset, etc.

Note

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.

◆ utcIsDST()

bool TZ::Timezone::utcIsDST ( time_t utc )

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

Parameters

utc

Return values

bool	true if time is within DST

◆ utcTimeTag()

const char* TZ::Timezone::utcTimeTag ( time_t utc )

inline

Return the appropriate time tag for a UTC time.

Parameters

utc	The time in UTC

Return values

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

The documentation for this class was generated from the following file:

Timezone.h

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ Timezone() [1/3]

◆ Timezone() [2/3]

◆ Timezone() [3/3]

Member Function Documentation

◆ fromPosix() [1/2]

◆ fromPosix() [2/2]

◆ getNextChange()

◆ getRule()

◆ getTransition()

◆ hasDaylightSavings()

◆ init()

◆ localTimeTag()

◆ locIsDST()

◆ makeZoned()

◆ operator bool()

◆ printTo()

◆ timeTag()

◆ toLocal()

◆ toString()

◆ toUTC()

◆ utcIsDST()

◆ utcTimeTag()