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

OffsetDateTime.h
1 /*
2 * MIT License
3 * Copyright (c) 2018 Brian T. Park
4 */
5
6 #ifndef ACE_TIME_OFFSET_DATE_TIME_H
7 #define ACE_TIME_OFFSET_DATE_TIME_H
8
9 #include <stdint.h>
10 #include "TimeOffset.h"
11 #include "LocalDateTime.h"
12
13 class Print;
14
15 namespace ace_time {
16
37 class OffsetDateTime {
38 public:
39
41 static OffsetDateTime forLocalDateTimeAndOffset(
42 const LocalDateTime& localDateTime, TimeOffset timeOffset) {
43 return OffsetDateTime(localDateTime, timeOffset);
44 }
45
61 static OffsetDateTime forComponents(int16_t year, uint8_t month,
62 uint8_t day, uint8_t hour, uint8_t minute, uint8_t second,
63 TimeOffset timeOffset, uint8_t fold = 0) {
64 auto ldt = LocalDateTime::forComponents(
65 year, month, day, hour, minute, second, fold);
66 return OffsetDateTime(ldt, timeOffset);
67 }
68
79 static OffsetDateTime forEpochSeconds(acetime_t epochSeconds,
80 TimeOffset timeOffset, uint8_t fold = 0) {
81 if (epochSeconds != LocalDate::kInvalidEpochSeconds) {
82 epochSeconds += timeOffset.toSeconds();
83 }
84 auto ldt = LocalDateTime::forEpochSeconds(epochSeconds, fold);
85 return OffsetDateTime(ldt, timeOffset);
86 }
87
98 static OffsetDateTime forUnixSeconds64(
99 int64_t unixSeconds, TimeOffset timeOffset, int8_t fold = 0) {
100 if (unixSeconds != LocalDate::kInvalidUnixSeconds64) {
101 unixSeconds += timeOffset.toSeconds();
102 }
103 auto ldt = LocalDateTime::forUnixSeconds64(unixSeconds, fold);
104 return OffsetDateTime(ldt, timeOffset);
105 }
106
123 static OffsetDateTime forDateString(const char* dateString);
124
130 static OffsetDateTime forDateString(const __FlashStringHelper* dateString);
131
139 static OffsetDateTime forDateStringChainable(const char*& dateString);
140
142 static OffsetDateTime forError() {
143 return OffsetDateTime(LocalDateTime::forError(), TimeOffset::forError());
144 }
145
147 explicit OffsetDateTime() {}
148
150 bool isError() const {
151 // Check mTimeOffset first because it's expected to be invalid more often.
152 return mTimeOffset.isError() || mLocalDateTime.isError();
153 }
154
156 int16_t year() const { return mLocalDateTime.year(); }
157
159 void year(int16_t year) { mLocalDateTime.year(year); }
160
162 uint8_t month() const { return mLocalDateTime.month(); }
163
165 void month(uint8_t month) { mLocalDateTime.month(month); }
166
168 uint8_t day() const { return mLocalDateTime.day(); }
169
171 void day(uint8_t day) { mLocalDateTime.day(day); }
172
174 uint8_t hour() const { return mLocalDateTime.hour(); }
175
177 void hour(uint8_t hour) { mLocalDateTime.hour(hour); }
178
180 uint8_t minute() const { return mLocalDateTime.minute(); }
181
183 void minute(uint8_t minute) { mLocalDateTime.minute(minute); }
184
186 uint8_t second() const { return mLocalDateTime.second(); }
187
189 void second(uint8_t second) { mLocalDateTime.second(second); }
190
192 uint8_t fold() const { return mLocalDateTime.fold(); }
193
195 void fold(uint8_t fold) { mLocalDateTime.fold(fold); }
196
198 uint8_t dayOfWeek() const { return mLocalDateTime.dayOfWeek(); }
199
201 TimeOffset timeOffset() const { return mTimeOffset; }
202
204 void timeOffset(TimeOffset timeOffset) { mTimeOffset = timeOffset; }
205
207 const LocalDateTime& localDateTime() const { return mLocalDateTime; }
208
210 const LocalDate& localDate() const { return mLocalDateTime.localDate(); }
211
213 const LocalTime& localTime() const { return mLocalDateTime.localTime(); }
214
221 OffsetDateTime convertToTimeOffset(TimeOffset timeOffset) const {
222 acetime_t epochSeconds = toEpochSeconds();
223 return OffsetDateTime::forEpochSeconds(epochSeconds, timeOffset);
224 }
225
231 int32_t toEpochDays() const {
232 if (isError()) return LocalDate::kInvalidEpochDays;
233
234 int32_t epochDays = mLocalDateTime.localDate().toEpochDays();
235
236 // Increment or decrement the day count depending on the time offset.
237 acetime_t timeOffset = mLocalDateTime.localTime().toSeconds()
238 - mTimeOffset.toSeconds();
239 if (timeOffset >= 86400) {
240 epochDays++;
241 } else if (timeOffset < 0) {
242 epochDays--;
243 }
244
245 return epochDays;
246 }
247
249 int32_t toUnixDays() const {
250 if (isError()) return LocalDate::kInvalidEpochDays;
251 return toEpochDays() + Epoch::daysToCurrentEpochFromUnixEpoch();
252 }
253
259 acetime_t toEpochSeconds() const {
260 if (isError()) return LocalDate::kInvalidEpochSeconds;
261 acetime_t epochSeconds = mLocalDateTime.toEpochSeconds();
262 if (epochSeconds == LocalDate::kInvalidEpochSeconds) {
263 return epochSeconds;
264 }
265 return epochSeconds - mTimeOffset.toSeconds();
266 }
267
275 int64_t toUnixSeconds64() const {
276 if (isError()) return LocalDate::kInvalidUnixSeconds64;
277 return mLocalDateTime.toUnixSeconds64() - mTimeOffset.toSeconds();
278 }
279
296 int8_t compareTo(const OffsetDateTime& that) const {
297 acetime_t thisSeconds = toEpochSeconds();
298 acetime_t thatSeconds = that.toEpochSeconds();
299 if (thisSeconds < thatSeconds) return -1;
300 if (thisSeconds > thatSeconds) return 1;
301 return 0;
302 }
303
309 void printTo(Print& printer) const;
310
311 // Use default copy constructor and assignment operator.
312 OffsetDateTime(const OffsetDateTime&) = default;
313 OffsetDateTime& operator=(const OffsetDateTime&) = default;
314
315 private:
316 friend bool operator==(const OffsetDateTime& a, const OffsetDateTime& b);
317
319 static const uint8_t kDateStringLength = 25;
320
322 explicit OffsetDateTime(const LocalDateTime& ldt, TimeOffset timeOffset):
323 mLocalDateTime(ldt),
324 mTimeOffset(timeOffset) {}
325
326 LocalDateTime mLocalDateTime;
327 TimeOffset mTimeOffset;
328 };
329
335 inline bool operator==(const OffsetDateTime& a, const OffsetDateTime& b) {
336 return a.mLocalDateTime == b.mLocalDateTime
337 && a.mTimeOffset == b.mTimeOffset;
338 }
339
341 inline bool operator!=(const OffsetDateTime& a, const OffsetDateTime& b) {
342 return ! (a == b);
343 }
344
345 }
346
347 #endif
ace_time::Epoch::daysToCurrentEpochFromUnixEpoch
static int32_t daysToCurrentEpochFromUnixEpoch()
Return the number of days from the Unix epoch (1970-01-01T00:00:00) to the current epoch.
Definition: Epoch.h:58
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::toUnixSeconds64
int64_t toUnixSeconds64() const
Return 64-bit seconds from Unix epoch 1970-01-01 00:00:00 UTC, after assuming that the date and time ...
Definition: LocalDateTime.h:245
ace_time::LocalDateTime::forEpochSeconds
static LocalDateTime forEpochSeconds(acetime_t epochSeconds, uint8_t fold=0)
Factory method.
Definition: LocalDateTime.h:63
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::LocalDateTime::day
uint8_t day() const
Return the day of the month.
Definition: LocalDateTime.h:168
ace_time::LocalDateTime::localDate
const LocalDate & localDate() const
Return the LocalDate.
Definition: LocalDateTime.h:201
ace_time::LocalDateTime::isError
bool isError() const
Return true if any component indicates an error condition.
Definition: LocalDateTime.h:151
ace_time::LocalDateTime::forUnixSeconds64
static LocalDateTime forUnixSeconds64(int64_t unixSeconds, uint8_t fold=0)
Factory method that takes the 64-bit number of seconds since Unix Epoch of 1970-01-01.
Definition: LocalDateTime.h:90
ace_time::LocalDateTime::forError
static LocalDateTime forError()
Factory method that returns an instance where isError() returns true.
Definition: LocalDateTime.h:143
ace_time::LocalDateTime::month
uint8_t month() const
Return the month with January=1, December=12.
Definition: LocalDateTime.h:162
ace_time::LocalDateTime::fold
uint8_t fold() const
Return the fold.
Definition: LocalDateTime.h:192
ace_time::LocalDateTime::second
uint8_t second() const
Return the second.
Definition: LocalDateTime.h:186
ace_time::LocalDateTime::minute
uint8_t minute() const
Return the minute.
Definition: LocalDateTime.h:180
ace_time::LocalDateTime::localTime
const LocalTime & localTime() const
Return the LocalTime.
Definition: LocalDateTime.h:204
ace_time::LocalDateTime::hour
uint8_t hour() const
Return the hour.
Definition: LocalDateTime.h:174
ace_time::LocalDateTime::dayOfWeek
uint8_t dayOfWeek() const
Return the day of the week, Monday=1, Sunday=7 (per ISO 8601).
Definition: LocalDateTime.h:198
ace_time::LocalDateTime::toEpochSeconds
acetime_t toEpochSeconds() const
Return seconds since the current AceTime epoch defined by Epoch::currentEpochYear().
Definition: LocalDateTime.h:230
ace_time::LocalDateTime::year
int16_t year() const
Return the year.
Definition: LocalDateTime.h:156
ace_time::LocalDate
The date (year, month, day) representing the date without regards to time zone.
Definition: LocalDate.h:46
ace_time::LocalDate::kInvalidEpochDays
static const int32_t kInvalidEpochDays
Sentinel epochDays which indicates an error.
Definition: LocalDate.h:81
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::LocalDate::toEpochDays
int32_t toEpochDays() const
Return number of days since the current epoch year sCurrentEpochYear.
Definition: LocalDate.h:352
ace_time::LocalTime
The time (hour, minute, second) fields representing the time without regards to the day or the time z...
Definition: LocalTime.h:27
ace_time::LocalTime::toSeconds
acetime_t toSeconds() const
Return the number of seconds since midnight.
Definition: LocalTime.h:145
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::forUnixSeconds64
static OffsetDateTime forUnixSeconds64(int64_t unixSeconds, TimeOffset timeOffset, int8_t fold=0)
Factory method that takes the number of seconds (64-bit) since Unix Epoch of 1970-01-01.
Definition: OffsetDateTime.h:98
ace_time::OffsetDateTime::localTime
const LocalTime & localTime() const
Return the LocalTime.
Definition: OffsetDateTime.h:213
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::forDateStringChainable
static OffsetDateTime forDateStringChainable(const char *&dateString)
Variant of forDateString() that updates the pointer to the next unprocessed character.
Definition: OffsetDateTime.cpp:52
ace_time::OffsetDateTime::month
void month(uint8_t month)
Set the month.
Definition: OffsetDateTime.h:165
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::timeOffset
void timeOffset(TimeOffset timeOffset)
Set the UTC offset.
Definition: OffsetDateTime.h:204
ace_time::OffsetDateTime::OffsetDateTime
OffsetDateTime()
Constructor.
Definition: OffsetDateTime.h:147
ace_time::OffsetDateTime::month
uint8_t month() const
Return the month with January=1, December=12.
Definition: OffsetDateTime.h:162
ace_time::OffsetDateTime::printTo
void printTo(Print &printer) const
Print OffsetDateTime to 'printer' in ISO 8601 format.
Definition: OffsetDateTime.cpp:14
ace_time::OffsetDateTime::minute
void minute(uint8_t minute)
Set the minute.
Definition: OffsetDateTime.h:183
ace_time::OffsetDateTime::forLocalDateTimeAndOffset
static OffsetDateTime forLocalDateTimeAndOffset(const LocalDateTime &localDateTime, TimeOffset timeOffset)
Factory method from LocalDateTime and TimeOffset.
Definition: OffsetDateTime.h:41
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::hour
void hour(uint8_t hour)
Set the hour.
Definition: OffsetDateTime.h:177
ace_time::OffsetDateTime::minute
uint8_t minute() const
Return the minute.
Definition: OffsetDateTime.h:180
ace_time::OffsetDateTime::convertToTimeOffset
OffsetDateTime convertToTimeOffset(TimeOffset timeOffset) const
Create a OffsetDateTime in a different UTC offset code (with the same epochSeconds).
Definition: OffsetDateTime.h:221
ace_time::OffsetDateTime::year
int16_t year() const
Return the year.
Definition: OffsetDateTime.h:156
ace_time::OffsetDateTime::day
void day(uint8_t day)
Set the day of the month.
Definition: OffsetDateTime.h:171
ace_time::OffsetDateTime::localDate
const LocalDate & localDate() const
Return the LocalDate.
Definition: OffsetDateTime.h:210
ace_time::OffsetDateTime::operator==
friend bool operator==(const OffsetDateTime &a, const OffsetDateTime &b)
Return true if two OffsetDateTime objects are equal in all components.
Definition: OffsetDateTime.h:335
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::forEpochSeconds
static OffsetDateTime forEpochSeconds(acetime_t epochSeconds, TimeOffset timeOffset, uint8_t fold=0)
Factory method.
Definition: OffsetDateTime.h:79
ace_time::OffsetDateTime::year
void year(int16_t year)
Set the year.
Definition: OffsetDateTime.h:159
ace_time::OffsetDateTime::second
void second(uint8_t second)
Set the second.
Definition: OffsetDateTime.h:189
ace_time::OffsetDateTime::fold
void fold(uint8_t fold)
Set the fold.
Definition: OffsetDateTime.h:195
ace_time::OffsetDateTime::second
uint8_t second() const
Return the second.
Definition: OffsetDateTime.h:186
ace_time::OffsetDateTime::forComponents
static OffsetDateTime forComponents(int16_t year, uint8_t month, uint8_t day, uint8_t hour, uint8_t minute, uint8_t second, TimeOffset timeOffset, uint8_t fold=0)
Factory method using separated date, time, and UTC offset fields.
Definition: OffsetDateTime.h:61
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::TimeOffset::forError
static TimeOffset forError()
Return an error indicator.
Definition: TimeOffset.h:122
ace_time::TimeOffset::toSeconds
int32_t toSeconds() const
Return the time offset as seconds.
Definition: TimeOffset.h:131
ace_time::TimeOffset::isError
bool isError() const
Return true if this TimeOffset represents an error.
Definition: TimeOffset.h:165
ace_time::acetime_t
int32_t acetime_t
Type for the number of seconds from epoch.
Definition: common.h:24