AceTime  0.1
Date and time classes for Arduino that supports the TZ DAtabase, and a system clock synchronized 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::ZonedDateTime Class Reference

The date (year, month, day) and time (hour, minute, second) fields representing an instant in time. More...

#include <ZonedDateTime.h>

Public Member Functions

 ZonedDateTime ()
 Default constructor. More...
 
bool isError () const
 Return true if any component indicates an error condition. More...
 
int16_t year () const
 Return the year. More...
 
void year (int16_t year)
 Set the year given the full year. More...
 
int8_t yearTiny () const
 Return the single-byte year offset from year 2000. More...
 
void yearTiny (int8_t yearTiny)
 Set the single-byte year offset from year 2000. More...
 
uint8_t month () const
 Return the month with January=1, December=12. More...
 
void month (uint8_t month)
 Set the month. More...
 
uint8_t day () const
 Return the day of the month. More...
 
void day (uint8_t day)
 Set the day of the month. More...
 
uint8_t hour () const
 Return the hour. More...
 
void hour (uint8_t hour)
 Set the hour. More...
 
uint8_t minute () const
 Return the minute. More...
 
void minute (uint8_t minute)
 Set the minute. More...
 
uint8_t second () const
 Return the second. More...
 
void second (uint8_t second)
 Set the second. More...
 
uint8_t dayOfWeek () const
 Return the day of the week using ISO 8601 numbering where Monday=1 and Sunday=7.
 
TimeOffset timeOffset () const
 Return the offset zone of the OffsetDateTime. More...
 
const TimeZonetimeZone () const
 Return the time zone of the ZonedDateTime. More...
 
void timeZone (const TimeZone &timeZone)
 Set the time zone. More...
 
ZonedDateTime convertToTimeZone (const TimeZone &timeZone) const
 Create a ZonedDateTime in a different time zone (with the same epochSeconds).
 
void printTo (Print &printer) const
 Print ZonedDateTime to 'printer'. More...
 
acetime_t toEpochDays () const
 Return number of whole days since AceTime epoch (2000-01-01 00:00:00Z), taking into account the time zone.
 
acetime_t toUnixDays () const
 Return the number of days since Unix epoch (1970-01-01 00:00:00). More...
 
acetime_t toEpochSeconds () const
 Return seconds since AceTime epoch (2000-01-01 00:00:00Z), taking into account the time zone. More...
 
acetime_t toUnixSeconds () const
 Return the number of seconds from Unix epoch 1970-01-01 00:00:00Z. More...
 
int8_t compareTo (const ZonedDateTime &that) const
 Compare this ZonedDateTime with another ZonedDateTime, and return (<0, 0, >0) according to whether the epochSeconds is (a<b, a==b, a>b). More...
 
 ZonedDateTime (const ZonedDateTime &)=default
 
ZonedDateTimeoperator= (const ZonedDateTime &)=default
 

Static Public Member Functions

static ZonedDateTime forComponents (int16_t year, uint8_t month, uint8_t day, uint8_t hour, uint8_t minute, uint8_t second, const TimeZone &timeZone=TimeZone())
 Factory method using separated date, time, and time zone fields. More...
 
static ZonedDateTime forEpochSeconds (acetime_t epochSeconds, const TimeZone &timeZone=TimeZone())
 Factory method. More...
 
static ZonedDateTime forUnixSeconds (acetime_t unixSeconds, const TimeZone &timeZone=TimeZone())
 Factory method to create a ZonedDateTime using the number of seconds from Unix epoch.
 
static ZonedDateTime forDateString (const char *dateString)
 Factory method. More...
 
static ZonedDateTime forDateString (const __FlashStringHelper *dateString)
 Factory method. More...
 
static ZonedDateTime forError ()
 Return an instance whose isError() returns true. More...
 

Static Public Attributes

static const acetime_t kInvalidEpochSeconds = LocalTime::kInvalidSeconds
 

Friends

bool operator== (const ZonedDateTime &a, const ZonedDateTime &b)
 Return true if two ZonedDateTime objects are equal in all components. More...
 
bool operator!= (const ZonedDateTime &a, const ZonedDateTime &b)
 Return true if two ZonedDateTime objects are not equal. More...
 

Detailed Description

The date (year, month, day) and time (hour, minute, second) fields representing an instant in time.

In an 8-bit implementation, the year field is internally represented as a int8_t number from -128 to 127 representing the year 1872 to 2127 inclusive. In a 16-bit implementation, the year field is an int16_t, so can represent years from 0000-9999 inclusive.

The "epoch" for this library is 2000-01-01 00:00:00Z. The dayOfWeek (1=Sunday, 7=Saturday) is calculated internally from the date components. Changing the timeZone does not affect the dayOfWeek.

Some parts of this class was inspired by the org.joda.DateTime of http://www.joda.org and java.time.ZonedDateTime of JDK8.

Definition at line 28 of file ZonedDateTime.h.

Constructor & Destructor Documentation

ace_time::ZonedDateTime::ZonedDateTime ( )
inlineexplicit

Default constructor.

Definition at line 132 of file ZonedDateTime.h.

Member Function Documentation

int8_t ace_time::ZonedDateTime::compareTo ( const ZonedDateTime that) const
inline

Compare this ZonedDateTime with another ZonedDateTime, and return (<0, 0, >0) according to whether the epochSeconds is (a<b, a==b, a>b).

The dayOfWeek field is ignored but the time zone is used. This method can return 0 (equal) even if the operator==() returns false if the two ZonedDateTime objects are in different time zones.

Definition at line 256 of file ZonedDateTime.h.

uint8_t ace_time::ZonedDateTime::day ( ) const
inline

Return the day of the month.

Definition at line 156 of file ZonedDateTime.h.

void ace_time::ZonedDateTime::day ( uint8_t  day)
inline

Set the day of the month.

Definition at line 159 of file ZonedDateTime.h.

static ZonedDateTime ace_time::ZonedDateTime::forComponents ( int16_t  year,
uint8_t  month,
uint8_t  day,
uint8_t  hour,
uint8_t  minute,
uint8_t  second,
const TimeZone timeZone = TimeZone() 
)
inlinestatic

Factory method using separated date, time, and time zone fields.

This is intended mostly for testing purposes. Most production code will use the forEpochSeconds() method.

The TimeOffset at the given date/time component is calculated using the ZoneSpecifier::getUtcOffsetForDateTime() determined by the actual subtype of ZoneSpecifier held by the given timeZone.

Parameters
year[1872-2127] for 8-bit implementation, [0000-9999] for 16-bit implementation
monthmonth with January=1, December=12
dayday of month (1-31)
hourhour (0-23)
minuteminute (0-59)
secondsecond (0-59), does not support leap seconds
timeZonepointer to an existing TimeZone instance. Optional, not nullable. Default is UTC TimeZone.

Definition at line 51 of file ZonedDateTime.h.

static ZonedDateTime ace_time::ZonedDateTime::forDateString ( const char *  dateString)
inlinestatic

Factory method.

Create a ZonedDateTime from the ISO 8601 date string. If the string cannot be parsed, then isError() on the constructed object returns true.

Parameters
dateStringa string in ISO 8601 format "YYYY-MM-DDThh:mm:ss+hh:mm", but currently, the parser is very lenient and does not detect most errors. It cares mostly about the positional placement of the various components. It does not validate the separation characters like '-' or ':'. For example, both of the following will parse to the exactly same ZonedDateTime object: "2018-08-31T13:48:01-07:00" "2018/08/31 13#48#01-07#00"

Definition at line 112 of file ZonedDateTime.h.

static ZonedDateTime ace_time::ZonedDateTime::forDateString ( const __FlashStringHelper *  dateString)
inlinestatic

Factory method.

Create a ZonedDateTime from date string in flash memory F() strings. Mostly for unit testing.

Definition at line 121 of file ZonedDateTime.h.

static ZonedDateTime ace_time::ZonedDateTime::forEpochSeconds ( acetime_t  epochSeconds,
const TimeZone timeZone = TimeZone() 
)
inlinestatic

Factory method.

Create the ZonedDateTime from epochSeconds as seen from the given time zone. If the time zone's offset is negative, then (epochSeconds >= TimeZone::effectiveOffsetSeconds().toEpochSeconds()) must be true. Otherwise, the local time will be in the year 1999, which cannot be represented by a 2-digit year beginning with the year 2000. The dayOfWeek will be calculated internally.

Parameters
epochSecondsNumber of seconds from AceTime epoch (2000-01-01 00:00:00Z). A value of kInvalidEpochSeconds is a sentinel is considered to be an error and causes isError() to return true.
timeZoneOptional, not nullable. Default is UTC TimeZone.

Definition at line 73 of file ZonedDateTime.h.

static ZonedDateTime ace_time::ZonedDateTime::forError ( )
inlinestatic

Return an instance whose isError() returns true.

Definition at line 127 of file ZonedDateTime.h.

uint8_t ace_time::ZonedDateTime::hour ( ) const
inline

Return the hour.

Definition at line 162 of file ZonedDateTime.h.

void ace_time::ZonedDateTime::hour ( uint8_t  hour)
inline

Set the hour.

Definition at line 165 of file ZonedDateTime.h.

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

Return true if any component indicates an error condition.

Definition at line 135 of file ZonedDateTime.h.

uint8_t ace_time::ZonedDateTime::minute ( ) const
inline

Return the minute.

Definition at line 168 of file ZonedDateTime.h.

void ace_time::ZonedDateTime::minute ( uint8_t  minute)
inline

Set the minute.

Definition at line 171 of file ZonedDateTime.h.

uint8_t ace_time::ZonedDateTime::month ( ) const
inline

Return the month with January=1, December=12.

Definition at line 150 of file ZonedDateTime.h.

void ace_time::ZonedDateTime::month ( uint8_t  month)
inline

Set the month.

Definition at line 153 of file ZonedDateTime.h.

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

Print ZonedDateTime to 'printer'.

Does not implement Printable to avoid memory cost of vtable pointer.

Definition at line 11 of file ZonedDateTime.cpp.

uint8_t ace_time::ZonedDateTime::second ( ) const
inline

Return the second.

Definition at line 174 of file ZonedDateTime.h.

void ace_time::ZonedDateTime::second ( uint8_t  second)
inline

Set the second.

Definition at line 177 of file ZonedDateTime.h.

TimeOffset ace_time::ZonedDateTime::timeOffset ( ) const
inline

Return the offset zone of the OffsetDateTime.

Definition at line 186 of file ZonedDateTime.h.

const TimeZone& ace_time::ZonedDateTime::timeZone ( ) const
inline

Return the time zone of the ZonedDateTime.

Definition at line 189 of file ZonedDateTime.h.

void ace_time::ZonedDateTime::timeZone ( const TimeZone timeZone)
inline

Set the time zone.

Note that this does not convert a given ZonedDateTime into a different TimeZone. Use converToTimeZone() instead.

Definition at line 195 of file ZonedDateTime.h.

acetime_t ace_time::ZonedDateTime::toEpochSeconds ( ) const
inline

Return seconds since AceTime epoch (2000-01-01 00:00:00Z), taking into account the time zone.

Normally, Julian day starts at 12:00:00. We modify the formula given in wiki page to start the Gregorian day at 00:00:00. See https://en.wikipedia.org/wiki/Julian_day

Definition at line 234 of file ZonedDateTime.h.

acetime_t ace_time::ZonedDateTime::toUnixDays ( ) const
inline

Return the number of days since Unix epoch (1970-01-01 00:00:00).

Definition at line 221 of file ZonedDateTime.h.

acetime_t ace_time::ZonedDateTime::toUnixSeconds ( ) const
inline

Return the number of seconds from Unix epoch 1970-01-01 00:00:00Z.

The return type is a acetime_t which can represent a range of 136 years.

Tip: You can use the command 'date +s -d {iso8601date}' on a Unix box to print the unix seconds.

Definition at line 245 of file ZonedDateTime.h.

int16_t ace_time::ZonedDateTime::year ( ) const
inline

Return the year.

Definition at line 138 of file ZonedDateTime.h.

void ace_time::ZonedDateTime::year ( int16_t  year)
inline

Set the year given the full year.

Definition at line 141 of file ZonedDateTime.h.

int8_t ace_time::ZonedDateTime::yearTiny ( ) const
inline

Return the single-byte year offset from year 2000.

Definition at line 144 of file ZonedDateTime.h.

void ace_time::ZonedDateTime::yearTiny ( int8_t  yearTiny)
inline

Set the single-byte year offset from year 2000.

Definition at line 147 of file ZonedDateTime.h.

Friends And Related Function Documentation

bool operator!= ( const ZonedDateTime a,
const ZonedDateTime b 
)
friend

Return true if two ZonedDateTime objects are not equal.

Definition at line 293 of file ZonedDateTime.h.

bool operator== ( const ZonedDateTime a,
const ZonedDateTime b 
)
friend

Return true if two ZonedDateTime objects are equal in all components.

Optimized for small changes in the less signficant fields, such as 'second' or 'minute'. The dayOfWeek is a derived field so it is not explicitly used to test equality, but it follows that if all the other fields are identical, thenthe dayOfWeek must also be equal.

Definition at line 287 of file ZonedDateTime.h.


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