A thin wrapper that represents a time offset from a reference point, usually 00:00 at UTC, but not always. More...

#include <TimeOffset.h>

Public Member Functions
	TimeOffset ()
	Constructor. More...

int16_t	toMinutes () const
	Return the time offset as minutes.

int32_t	toSeconds () const
	Return the time offset as seconds.

void	toHourMinute (int8_t &hour, int8_t &minute) const
	Extract hour and minute representation of the offset. More...

void	toHourMinuteSecond (int8_t &hour, int8_t &minute, int8_t &second) const
	Extract hour, minute, second from the offset. More...

bool	isZero () const
	Returns true if offset is 00:00. More...

bool	isError () const
	Return true if this TimeOffset represents an error.

void	printTo (Print &printer) const
	Print the human readable string, including a "-" or "+" prefix, in the form of "+/-hh:mm" or "+/-hh:mm:ss". More...

	TimeOffset (const TimeOffset &)=default

TimeOffset &	operator= (const TimeOffset &)=default

Static Public Member Functions
static TimeOffset	forHours (int8_t hours)
	Create TimeOffset with the corresponding hour offset. More...

static TimeOffset	forHourMinute (int8_t hour, int8_t minute)
	Create TimeOffset from (hour, minute) offset. More...

static TimeOffset	forHourMinuteSecond (int8_t hour, int8_t minute, int8_t second)
	Create a TimeOffset fro (hour, minute, second) offset. More...

static TimeOffset	forMinutes (int16_t minutes)
	Create TimeOffset from minutes from 00:00.

static TimeOffset	forSeconds (int32_t seconds)
	Create TimeOffset from seconds from 00:00.

static TimeOffset	forOffsetString (const char *offsetString)
	Create from an offset string (e.g. More...

static TimeOffset	forOffsetStringChainable (const char *&offsetString)
	Variant of forOffsetString() that updates the string pointer to the next unprocessed character. More...

static TimeOffset	forError ()
	Return an error indicator.

Friends
bool	operator== (const TimeOffset &a, const TimeOffset &b)

void	time_offset_mutation::incrementHour (TimeOffset &offset)

void	time_offset_mutation::increment15Minutes (TimeOffset &offset)

Detailed Description

A thin wrapper that represents a time offset from a reference point, usually 00:00 at UTC, but not always.

Use one of the static factory methods to create an instance. For example, each of the following creates a TimeOffset of -08:00:

TimeOffset tz = TimeOffset::forHours(-8);
TimeOffset tz = TimeOffset::forHourMinute(-8, 0);
TimeOffset tz = TimeOffset::forMinutes(-480);
TimeOffset tz = TimeOffset::forOffsetString("-08:00");

You can use the default constructor to create a +00:00 TimeOffset:

TimeOffset offset;

The current implementation has a resolution of 1-minute (using an internal int16_t type). The previous implementation (< v0.7) had a resolution of 15-minutes (using an internal int8_t type) because that was sufficient to handle all current timezones for years >= 2018 (determined by looking at https://en.wikipedia.org/wiki/List_of_UTC_time_offsets, and the TZ Database zonefiles itself through the tzcompiler.py script). However, 15-minute resolution is not sufficient to handle a handful of timezones in the past (years 2000 to 2011 or so). So I changed the implementation to use 2 bytes to handle 1-minute resolution.

This class does NOT know about the TZ Database (aka Olson database) https://en.wikipedia.org/wiki/Tz_database. That functionality is implemented in the TimeZone class.

Definition at line 56 of file TimeOffset.h.

Constructor & Destructor Documentation

◆ TimeOffset()

ace_time::TimeOffset::TimeOffset ( )

inlineexplicit

Constructor.

Create a time offset of 0.

Definition at line 125 of file TimeOffset.h.

Member Function Documentation

◆ forHourMinute()

static TimeOffset ace_time::TimeOffset::forHourMinute	(	int8_t	hour,
		int8_t	minute
	)

inlinestatic

Create TimeOffset from (hour, minute) offset.

If the offset is negative, then the negative sign must be added to both the hour and minute components. This allows a negative offset of less than -01:00 to be created. For example, -07:30 is created by 'forHourMinute(-7, -30)' (not 'forHourMinute(-7, 30), and -00:15 is created by 'forHourMinute(0, -15)'.

Definition at line 74 of file TimeOffset.h.

◆ forHourMinuteSecond()

static TimeOffset ace_time::TimeOffset::forHourMinuteSecond	(	int8_t	hour,
		int8_t	minute,
		int8_t	second
	)

inlinestatic

Create a TimeOffset fro (hour, minute, second) offset.

If the offset is is negative, the negative sign must be added to all fields. For example, -01:02:03 is created by forHourMinuteSecond(-1, -2, -3).

Definition at line 84 of file TimeOffset.h.

◆ forHours()

static TimeOffset ace_time::TimeOffset::forHours ( int8_t hours )

inlinestatic

Create TimeOffset with the corresponding hour offset.

For example, -08:00 is 'forHours(-8)'.

Definition at line 62 of file TimeOffset.h.

◆ forOffsetString()

TimeOffset ace_time::TimeOffset::forOffsetString ( const char * offsetString )

static

Create from an offset string (e.g.

"-07:00", "+01:00", "-02:15:33"). Intended mostly for testing purposes. Returns TimeOffset::forError() if a parsing error occurs.

NOTE: Error checking is not robust, and can be corrupted easily by a misformatted string, or a string with an invalid number of characters. This is intended only for debugging purposes, not for production quality.

Definition at line 38 of file TimeOffset.cpp.

◆ forOffsetStringChainable()

TimeOffset ace_time::TimeOffset::forOffsetStringChainable ( const char *& offsetString )

static

Variant of forOffsetString() that updates the string pointer to the next unprocessed character.

The resulting pointer can be passed to another forDateStringInternal() method to chain the parsing.

This method assumes that the offsetString is sufficiently long. Returns TimeOffset::forError() if a parsing error occurs.

Definition at line 48 of file TimeOffset.cpp.

◆ isZero()

bool ace_time::TimeOffset::isZero ( ) const

inline

Returns true if offset is 00:00.

If this represents a time zone, then isZero means that it is UTC. If this represents a DST delta offset, then isZero means that the time zone is in standard time.

Definition at line 162 of file TimeOffset.h.

◆ printTo()

void ace_time::TimeOffset::printTo ( Print & printer ) const

Print the human readable string, including a "-" or "+" prefix, in the form of "+/-hh:mm" or "+/-hh:mm:ss".

If the 'second' field is 0, then only the hour and minute fields are printed (e.g. "-08:00"), instead of all three fields (e.g. "+08:15:20").

Definition at line 15 of file TimeOffset.cpp.

◆ toHourMinute()

void ace_time::TimeOffset::toHourMinute	(	int8_t &	hour,
		int8_t &	minute
	)		const

inline

Extract hour and minute representation of the offset.

This the inverse of 'forHourMinute()'. If the TimeOffset is negative, then both the hour and minute components will contain the negative sign.

Definition at line 138 of file TimeOffset.h.

◆ toHourMinuteSecond()

void ace_time::TimeOffset::toHourMinuteSecond	(	int8_t &	hour,
		int8_t &	minute,
		int8_t &	second
	)		const

inline

Extract hour, minute, second from the offset.

Truncation is performed towards zero, so if the offset seconds is negative, each of the hour, minute, second fields will be negative.

Definition at line 149 of file TimeOffset.h.

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

/home/brian/src/AceTimeSuite/libraries/AceTimeLib/src/ace_time/TimeOffset.h
/home/brian/src/AceTimeSuite/libraries/AceTimeLib/src/ace_time/TimeOffset.cpp

Public Member Functions

Static Public Member Functions

Friends

Detailed Description

Constructor & Destructor Documentation

◆ TimeOffset()

Member Function Documentation

◆ forHourMinute()

◆ forHourMinuteSecond()

◆ forHours()

◆ forOffsetString()

◆ forOffsetStringChainable()

◆ isZero()

◆ printTo()

◆ toHourMinute()

◆ toHourMinuteSecond()