AceTime 3.0.0 Date and time classes for Arduino that support timezones from the TZ Database.

ZonedDateTime.h
1 /*
2 * MIT License
3 * Copyright (c) 2018 Brian T. Park
4 */
5
6 #ifndef ACE_TIME_ZONED_DATE_TIME_H
7 #define ACE_TIME_ZONED_DATE_TIME_H
8
9 #include <stdint.h>
10 #include "OffsetDateTime.h"
11 #include "TimeZone.h"
12
13 class Print;
14
15 namespace ace_time {
16
36 class ZonedDateTime {
37 public:
55 static ZonedDateTime forComponents(
56 int16_t year, uint8_t month, uint8_t day,
57 uint8_t hour, uint8_t minute, uint8_t second,
58 const TimeZone& timeZone, uint8_t fold = 0) {
59 auto ldt = LocalDateTime::forComponents(
60 year, month, day, hour, minute, second, fold);
61 return forLocalDateTime(ldt, timeZone);
62 }
63
75 static ZonedDateTime forLocalDateTime(
76 const LocalDateTime& ldt,
77 const TimeZone& timeZone) {
78 auto odt = timeZone.getOffsetDateTime(ldt);
79 return ZonedDateTime(odt, timeZone);
80 }
93 static ZonedDateTime forEpochSeconds(acetime_t epochSeconds,
94 const TimeZone& timeZone) {
95 OffsetDateTime odt = (epochSeconds == LocalDate::kInvalidEpochSeconds)
96 ? OffsetDateTime::forError()
97 : timeZone.getOffsetDateTime(epochSeconds);
98 return ZonedDateTime(odt, timeZone);
99 }
100
119 static ZonedDateTime forUnixSeconds64(
120 int64_t unixSeconds, const TimeZone& timeZone) {
121 acetime_t epochSeconds;
122 if (unixSeconds == LocalDate::kInvalidUnixSeconds64) {
123 epochSeconds = LocalDate::kInvalidEpochSeconds;
124 } else {
125 epochSeconds = unixSeconds
126 - Epoch::secondsToCurrentEpochFromUnixEpoch64();
127 }
128 return forEpochSeconds(epochSeconds, timeZone);
129 }
130
144 static ZonedDateTime forDateString(const char* dateString) {
145 OffsetDateTime dt = OffsetDateTime::forDateString(dateString);
146 return ZonedDateTime(dt, TimeZone::forTimeOffset(dt.timeOffset()));
147 }
148
153 static ZonedDateTime forDateString(const __FlashStringHelper* dateString) {
154 OffsetDateTime dt = OffsetDateTime::forDateString(dateString);
155 return ZonedDateTime(dt, TimeZone::forTimeOffset(dt.timeOffset()));
156 }
157
159 static ZonedDateTime forError() {
160 return ZonedDateTime(OffsetDateTime::forError(), TimeZone());
161 }
162
164 explicit ZonedDateTime() {}
165
167 bool isError() const { return mOffsetDateTime.isError(); }
168
170 int16_t year() const { return mOffsetDateTime.year(); }
171
173 void year(int16_t year) { mOffsetDateTime.year(year); }
174
176 uint8_t month() const { return mOffsetDateTime.month(); }
177
179 void month(uint8_t month) { mOffsetDateTime.month(month); }
180
182 uint8_t day() const { return mOffsetDateTime.day(); }
183
185 void day(uint8_t day) { mOffsetDateTime.day(day); }
186
188 uint8_t hour() const { return mOffsetDateTime.hour(); }
189
191 void hour(uint8_t hour) { mOffsetDateTime.hour(hour); }
192
194 uint8_t minute() const { return mOffsetDateTime.minute(); }
195
197 void minute(uint8_t minute) { mOffsetDateTime.minute(minute); }
198
200 uint8_t second() const { return mOffsetDateTime.second(); }
201
203 void second(uint8_t second) { mOffsetDateTime.second(second); }
204
206 uint8_t fold() const { return mOffsetDateTime.fold(); }
207
209 void fold(uint8_t fold) { mOffsetDateTime.fold(fold); }
210
215 uint8_t dayOfWeek() const { return mOffsetDateTime.dayOfWeek(); }
216
218 const TimeZone& timeZone() const { return mTimeZone; }
219
224 void timeZone(const TimeZone& timeZone) { mTimeZone = timeZone; }
225
227 TimeOffset timeOffset() const { return mOffsetDateTime.timeOffset(); }
228
230 const LocalDateTime& localDateTime() const {
231 return mOffsetDateTime.localDateTime();
232 }
233
235 const OffsetDateTime& offsetDateTime() const {
236 return mOffsetDateTime;
237 }
238
255 void normalize() {
256 mOffsetDateTime = mTimeZone.getOffsetDateTime(localDateTime());
257 }
258
263 ZonedDateTime convertToTimeZone(const TimeZone& timeZone) const {
264 acetime_t epochSeconds = toEpochSeconds();
265 return ZonedDateTime::forEpochSeconds(epochSeconds, timeZone);
266 }
267
273 int32_t toEpochDays() const {
274 return mOffsetDateTime.toEpochDays();
275 }
276
278 int32_t toUnixDays() const {
279 return mOffsetDateTime.toUnixDays();
280 }
281
287 acetime_t toEpochSeconds() const {
288 return mOffsetDateTime.toEpochSeconds();
289 }
290
298 int64_t toUnixSeconds64() const {
299 return mOffsetDateTime.toUnixSeconds64();
300 }
301
318 int8_t compareTo(const ZonedDateTime& that) const {
319 return mOffsetDateTime.compareTo(that.mOffsetDateTime);
320 }
321
327 void printTo(Print& printer) const;
328
329 // Use default copy constructor and assignment operator.
330 ZonedDateTime(const ZonedDateTime&) = default;
331 ZonedDateTime& operator=(const ZonedDateTime&) = default;
332
333 private:
335 static const uint8_t kDateStringLength = 25;
336
337 friend bool operator==(const ZonedDateTime& a, const ZonedDateTime& b);
338
340 ZonedDateTime(const OffsetDateTime& offsetDateTime, const TimeZone& tz):
341 mOffsetDateTime(offsetDateTime),
342 mTimeZone(tz) {}
343
344 OffsetDateTime mOffsetDateTime;
345 TimeZone mTimeZone;
346 };
347
355 inline bool operator==(const ZonedDateTime& a, const ZonedDateTime& b) {
356 return a.mOffsetDateTime == b.mOffsetDateTime
357 && a.mTimeZone == b.mTimeZone;
358 }
359
361 inline bool operator!=(const ZonedDateTime& a, const ZonedDateTime& b) {
362 return ! (a == b);
363 }
364
365 }
366
367 #endif
ace_time::Epoch::secondsToCurrentEpochFromUnixEpoch64
static int64_t secondsToCurrentEpochFromUnixEpoch64()
Return the number of seconds from the Unix epoch (1970-01-01T00:00:00) to the current epoch.
Definition: Epoch.h:69
ace_time::LocalDateTime
Class that holds the date-time as the components (year, month, day, hour, minute, second) without reg...
Definition: LocalDateTime.h:30
ace_time::LocalDateTime::forComponents
static LocalDateTime forComponents(int16_t year, uint8_t month, uint8_t day, uint8_t hour, uint8_t minute, uint8_t second, uint8_t fold=0)
Factory method using separated date and time components.
Definition: LocalDateTime.h:44
ace_time::LocalDate::kInvalidUnixSeconds64
static const int64_t kInvalidUnixSeconds64
Sentinel unixSeconds64 which indicates an error.
Definition: LocalDate.h:87
ace_time::LocalDate::kInvalidEpochSeconds
static const int32_t kInvalidEpochSeconds
Sentinel epochSeconds which indicates an error.
Definition: LocalDate.h:84
ace_time::OffsetDateTime
The date (year, month, day), time (hour, minute, second) and fixed offset from UTC (timeOffset).
Definition: OffsetDateTime.h:37
ace_time::OffsetDateTime::day
uint8_t day() const
Return the day of the month.
Definition: OffsetDateTime.h:168
ace_time::OffsetDateTime::timeOffset
TimeOffset timeOffset() const
Return the UTC offset of the OffsetDateTime.
Definition: OffsetDateTime.h:201
ace_time::OffsetDateTime::toUnixSeconds64
int64_t toUnixSeconds64() const
Return the 64-bit number of seconds from Unix epoch 1970-01-01 00:00:00 UTC.
Definition: OffsetDateTime.h:275
ace_time::OffsetDateTime::isError
bool isError() const
Return true if any component indicates an error condition.
Definition: OffsetDateTime.h:150
ace_time::OffsetDateTime::localDateTime
const LocalDateTime & localDateTime() const
Return the LocalDateTime.
Definition: OffsetDateTime.h:207
ace_time::OffsetDateTime::hour
uint8_t hour() const
Return the hour.
Definition: OffsetDateTime.h:174
ace_time::OffsetDateTime::month
uint8_t month() const
Return the month with January=1, December=12.
Definition: OffsetDateTime.h:162
ace_time::OffsetDateTime::toEpochSeconds
acetime_t toEpochSeconds() const
Return seconds since AceTime epoch taking into account the UTC offset.
Definition: OffsetDateTime.h:259
ace_time::OffsetDateTime::forError
static OffsetDateTime forError()
Factory method that returns an instance whose isError() is true.
Definition: OffsetDateTime.h:142
ace_time::OffsetDateTime::fold
uint8_t fold() const
Return the fold.
Definition: OffsetDateTime.h:192
ace_time::OffsetDateTime::compareTo
int8_t compareTo(const OffsetDateTime &that) const
Compare 'this' OffsetDateTime with 'that' OffsetDateTime, and return (<0, 0, >0) according to whether...
Definition: OffsetDateTime.h:296
ace_time::OffsetDateTime::minute
uint8_t minute() const
Return the minute.
Definition: OffsetDateTime.h:180
ace_time::OffsetDateTime::year
int16_t year() const
Return the year.
Definition: OffsetDateTime.h:156
ace_time::OffsetDateTime::forDateString
static OffsetDateTime forDateString(const char *dateString)
Factory method.
Definition: OffsetDateTime.cpp:27
ace_time::OffsetDateTime::dayOfWeek
uint8_t dayOfWeek() const
Return the day of the week, Monday=1, Sunday=7 (per ISO 8601).
Definition: OffsetDateTime.h:198
ace_time::OffsetDateTime::toEpochDays
int32_t toEpochDays() const
Return number of whole days since AceTime epoch taking into account the UTC offset.
Definition: OffsetDateTime.h:231
ace_time::OffsetDateTime::toUnixDays
int32_t toUnixDays() const
Return the number of days since Unix epoch (1970-01-01 00:00:00).
Definition: OffsetDateTime.h:249
ace_time::OffsetDateTime::second
uint8_t second() const
Return the second.
Definition: OffsetDateTime.h:186
ace_time::TimeOffset
A thin wrapper that represents a time offset from a reference point, usually 00:00 at UTC,...
Definition: TimeOffset.h:56
ace_time::TimeZone
Class that describes a time zone.
Definition: TimeZone.h:86
ace_time::TimeZone::getOffsetDateTime
OffsetDateTime getOffsetDateTime(const LocalDateTime &ldt) const
Return the best estimate of the OffsetDateTime at the given LocalDateTime for the current TimeZone.
Definition: TimeZone.h:386
ace_time::TimeZone::forTimeOffset
static TimeZone forTimeOffset(TimeOffset stdOffset, TimeOffset dstOffset=TimeOffset())
Factory method to create from a UTC offset and an optional DST offset.
Definition: TimeZone.h:115
ace_time::ZonedDateTime
The date (year, month, day), time (hour, minute, second), and a timeZone object that supports the zon...
Definition: ZonedDateTime.h:36
ace_time::ZonedDateTime::forComponents
static ZonedDateTime forComponents(int16_t year, uint8_t month, uint8_t day, uint8_t hour, uint8_t minute, uint8_t second, const TimeZone &timeZone, uint8_t fold=0)
Factory method using separated date, time, and time zone fields.
Definition: ZonedDateTime.h:55
ace_time::ZonedDateTime::compareTo
int8_t compareTo(const ZonedDateTime &that) const
Compare 'this' ZonedDateTime with 'that' ZonedDateTime, and return (<0, 0, >0) according to whether t...
Definition: ZonedDateTime.h:318
ace_time::ZonedDateTime::timeZone
const TimeZone & timeZone() const
Return the time zone of the ZonedDateTime.
Definition: ZonedDateTime.h:218
ace_time::ZonedDateTime::hour
uint8_t hour() const
Return the hour.
Definition: ZonedDateTime.h:188
ace_time::ZonedDateTime::fold
void fold(uint8_t fold)
Set the fold.
Definition: ZonedDateTime.h:209
ace_time::ZonedDateTime::toEpochDays
int32_t toEpochDays() const
Return number of whole days since AceTime epoch taking into account the time zone.
Definition: ZonedDateTime.h:273
ace_time::ZonedDateTime::year
int16_t year() const
Return the year.
Definition: ZonedDateTime.h:170
ace_time::ZonedDateTime::printTo
void printTo(Print &printer) const
Print ZonedDateTime to 'printer'.
Definition: ZonedDateTime.cpp:12
ace_time::ZonedDateTime::dayOfWeek
uint8_t dayOfWeek() const
Return the day of the week using ISO 8601 numbering where Monday=1 and Sunday=7.
Definition: ZonedDateTime.h:215
ace_time::ZonedDateTime::forLocalDateTime
static ZonedDateTime forLocalDateTime(const LocalDateTime &ldt, const TimeZone &timeZone)
Factory method using LocalDateTime and time zone fields.
Definition: ZonedDateTime.h:75
ace_time::ZonedDateTime::operator==
friend bool operator==(const ZonedDateTime &a, const ZonedDateTime &b)
Return true if two ZonedDateTime objects are equal in all components.
Definition: ZonedDateTime.h:355
ace_time::ZonedDateTime::forDateString
static ZonedDateTime forDateString(const __FlashStringHelper *dateString)
Factory method.
Definition: ZonedDateTime.h:153
ace_time::ZonedDateTime::fold
uint8_t fold() const
Return the fold.
Definition: ZonedDateTime.h:206
ace_time::ZonedDateTime::convertToTimeZone
ZonedDateTime convertToTimeZone(const TimeZone &timeZone) const
Create a ZonedDateTime in a different time zone (with the same epochSeconds).
Definition: ZonedDateTime.h:263
ace_time::ZonedDateTime::isError
bool isError() const
Return true if any component indicates an error condition.
Definition: ZonedDateTime.h:167
ace_time::ZonedDateTime::day
void day(uint8_t day)
Set the day of the month.
Definition: ZonedDateTime.h:185
ace_time::ZonedDateTime::minute
void minute(uint8_t minute)
Set the minute.
Definition: ZonedDateTime.h:197
ace_time::ZonedDateTime::toUnixSeconds64
int64_t toUnixSeconds64() const
Return the 64-bit number of seconds from Unix epoch 1970-01-01 00:00:00 UTC.
Definition: ZonedDateTime.h:298
ace_time::ZonedDateTime::day
uint8_t day() const
Return the day of the month.
Definition: ZonedDateTime.h:182
ace_time::ZonedDateTime::forUnixSeconds64
static ZonedDateTime forUnixSeconds64(int64_t unixSeconds, const TimeZone &timeZone)
Factory method to create a ZonedDateTime using the 64-bit number of seconds from Unix epoch.
Definition: ZonedDateTime.h:119
ace_time::ZonedDateTime::second
void second(uint8_t second)
Set the second.
Definition: ZonedDateTime.h:203
ace_time::ZonedDateTime::second
uint8_t second() const
Return the second.
Definition: ZonedDateTime.h:200
ace_time::ZonedDateTime::forError
static ZonedDateTime forError()
Return an instance whose isError() returns true.
Definition: ZonedDateTime.h:159
ace_time::ZonedDateTime::forEpochSeconds
static ZonedDateTime forEpochSeconds(acetime_t epochSeconds, const TimeZone &timeZone)
Factory method.
Definition: ZonedDateTime.h:93
ace_time::ZonedDateTime::year
void year(int16_t year)
Set the year given the full year.
Definition: ZonedDateTime.h:173
ace_time::ZonedDateTime::hour
void hour(uint8_t hour)
Set the hour.
Definition: ZonedDateTime.h:191
ace_time::ZonedDateTime::ZonedDateTime
ZonedDateTime()
Default constructor.
Definition: ZonedDateTime.h:164
ace_time::ZonedDateTime::toEpochSeconds
acetime_t toEpochSeconds() const
Return seconds since AceTime epoch taking into account the time zone.
Definition: ZonedDateTime.h:287
ace_time::ZonedDateTime::minute
uint8_t minute() const
Return the minute.
Definition: ZonedDateTime.h:194
ace_time::ZonedDateTime::timeZone
void timeZone(const TimeZone &timeZone)
Set the time zone.
Definition: ZonedDateTime.h:224
ace_time::ZonedDateTime::normalize
void normalize()
Normalize the ZonedDateTime after mutation.
Definition: ZonedDateTime.h:255
ace_time::ZonedDateTime::month
void month(uint8_t month)
Set the month.
Definition: ZonedDateTime.h:179
ace_time::ZonedDateTime::timeOffset
TimeOffset timeOffset() const
Return the offset zone of the OffsetDateTime.
Definition: ZonedDateTime.h:227
ace_time::ZonedDateTime::toUnixDays
int32_t toUnixDays() const
Return the number of days since Unix epoch (1970-01-01 00:00:00).
Definition: ZonedDateTime.h:278
ace_time::ZonedDateTime::forDateString
static ZonedDateTime forDateString(const char *dateString)
Factory method.
Definition: ZonedDateTime.h:144
ace_time::ZonedDateTime::localDateTime
const LocalDateTime & localDateTime() const
Return the LocalDateTime of the components.
Definition: ZonedDateTime.h:230
ace_time::ZonedDateTime::month
uint8_t month() const
Return the month with January=1, December=12.
Definition: ZonedDateTime.h:176
ace_time::ZonedDateTime::offsetDateTime
const OffsetDateTime & offsetDateTime() const
Return the OffsetDateTime of the components.
Definition: ZonedDateTime.h:235
ace_time::acetime_t
int32_t acetime_t
Type for the number of seconds from epoch.
Definition: common.h:24