AceTime
0.7
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.
|
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 | |
TimeOffset & | operator= (const TimeOffset &)=default |
Static Public Member Functions | |
static TimeOffset | forHours (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... | |
static const int16_t | kErrorMinutes = INT16_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) |
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:
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. Some residual methods handle "offsetCode" because the zoneinfo files in zonedb/ and zonedbx/ are encoded using a int8_t type to save flash memory space.
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 61 of file TimeOffset.h.
|
inlineexplicit |
|
inlinestatic |
Return an error indicator.
Definition at line 113 of file TimeOffset.h.
|
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 85 of file TimeOffset.h.
|
inlinestatic |
Create TimeOffset with the corresponding hour offset.
For example, -08:00 is 'forHours(-8)'.
Definition at line 73 of file TimeOffset.h.
|
inlinestatic |
Create TimeOffset from minutes from 00:00.
Definition at line 91 of file TimeOffset.h.
|
inlinestatic |
Create TimeOffset from the offset code.
offsetCode | the amount of time offset in 15-minute increments. |
Definition at line 120 of file TimeOffset.h.
|
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.
|
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.
|
inline |
Return true if this TimeOffset represents an error.
Definition at line 159 of file TimeOffset.h.
|
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 156 of file TimeOffset.h.
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.
|
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 146 of file TimeOffset.h.
|
inline |
Return the time offset as minutes.
Definition at line 132 of file TimeOffset.h.
|
inline |
Return the time offset as the number of 15 minute increments.
Definition at line 129 of file TimeOffset.h.
|
inline |
Return the time offset as seconds.
Definition at line 137 of file TimeOffset.h.
|
static |
Sentinel value that represents an error.
Definition at line 64 of file TimeOffset.h.
|
static |
Sentinel value that represents an error.
Definition at line 67 of file TimeOffset.h.