AceTime  0.6
Date and time classes for Arduino that support timezones from the TZ Database, and a system clock that can synchronize from an NTP server or an RTC chip.
Public Member Functions | Static Public Member Functions | Static Public Attributes | Friends | List of all members
ace_time::TimeOffset Class Reference

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...
 
int8_t toOffsetCode () const
 Return the time offset as the number of 15 minute increments. More...
 
int16_t toMinutes () const
 Return the time offset as minutes. More...
 
int32_t toSeconds () const
 Return the time offset as seconds. More...
 
void toHourMinute (int8_t &hour, int8_t &minute) const
 Extract hour and minute representation of 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. More...
 
void printTo (Print &printer) const
 Print the human readable string. More...
 
 TimeOffset (const TimeOffset &)=default
 
TimeOffsetoperator= (const TimeOffset &)=default
 

Static Public Member Functions

static TimeOffset forHour (int8_t hour)
 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 forMinutes (int16_t minutes)
 Create TimeOffset from minutes from 00:00. More...
 
static TimeOffset forOffsetString (const char *offsetString)
 Create from an offset string ("-07:00" or "+01:00"). 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. More...
 
static TimeOffset forOffsetCode (int8_t offsetCode)
 Create TimeOffset from the offset code. More...
 

Static Public Attributes

static const int8_t kErrorCode = INT8_MIN
 Sentinel value that represents an error. More...
 

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:

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

TimeOffset offset;

According to https://en.wikipedia.org/wiki/List_of_UTC_time_offsets, all time zones currently in use occur at 15 minute boundaries, and the smallest time zone is UTC-12:00 and the biggest time zone is UTC+14:00. Therefore, we can encode all currently used time zones as integer multiples of 15-minute offsets from UTC. This allows the TimeOffset to be stored as a single 8-bit signed integer. For the most part, the internal implementation of this class does not leak out to the outside world, so it should be relatively easy to change its implementation to a int16_t type to support 1-minute granularity instead of 15-minute granularity.

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 58 of file TimeOffset.h.

Constructor & Destructor Documentation

◆ TimeOffset()

ace_time::TimeOffset::TimeOffset ( )
inlineexplicit

Constructor.

Create a time offset of 0.

Definition at line 122 of file TimeOffset.h.

Member Function Documentation

◆ forError()

static TimeOffset ace_time::TimeOffset::forError ( )
inlinestatic

Return an error indicator.

Definition at line 110 of file TimeOffset.h.

◆ forHour()

static TimeOffset ace_time::TimeOffset::forHour ( int8_t  hour)
inlinestatic

Create TimeOffset with the corresponding hour offset.

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

Definition at line 67 of file TimeOffset.h.

◆ 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. The 'minute' must be in multiples of 15-minutes. 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 79 of file TimeOffset.h.

◆ forMinutes()

static TimeOffset ace_time::TimeOffset::forMinutes ( int16_t  minutes)
inlinestatic

Create TimeOffset from minutes from 00:00.

In the current implementation, the minutes is truncated to the 15-minute boundary towards 0.

Definition at line 88 of file TimeOffset.h.

◆ forOffsetCode()

static TimeOffset ace_time::TimeOffset::forOffsetCode ( int8_t  offsetCode)
inlinestatic

Create TimeOffset from the offset code.

Parameters
offsetCodethe amount of time offset in 15-minute increments.

Definition at line 117 of file TimeOffset.h.

◆ forOffsetString()

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

Create from an offset string ("-07:00" or "+01:00").

Intended mostly for testing purposes. Returns TimeOffset::forError() if a parsing error occurs.

Definition at line 32 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 41 of file TimeOffset.cpp.

◆ isError()

bool ace_time::TimeOffset::isError ( ) const
inline

Return true if this TimeOffset represents an error.

Definition at line 155 of file TimeOffset.h.

◆ 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 152 of file TimeOffset.h.

◆ printTo()

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

Print the human readable string.

For example, "-08:00".

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 142 of file TimeOffset.h.

◆ toMinutes()

int16_t ace_time::TimeOffset::toMinutes ( ) const
inline

Return the time offset as minutes.

Definition at line 128 of file TimeOffset.h.

◆ toOffsetCode()

int8_t ace_time::TimeOffset::toOffsetCode ( ) const
inline

Return the time offset as the number of 15 minute increments.

Definition at line 125 of file TimeOffset.h.

◆ toSeconds()

int32_t ace_time::TimeOffset::toSeconds ( ) const
inline

Return the time offset as seconds.

Definition at line 133 of file TimeOffset.h.

Member Data Documentation

◆ kErrorCode

const int8_t ace_time::TimeOffset::kErrorCode = INT8_MIN
static

Sentinel value that represents an error.

Definition at line 61 of file TimeOffset.h.


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