AceTime  1.7.1
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.
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 
34  public:
35 
40  }
41 
53  static OffsetDateTime forComponents(int16_t year, uint8_t month, uint8_t
54  day, uint8_t hour, uint8_t minute, uint8_t second, TimeOffset
55  timeOffset) {
57  second);
58  return OffsetDateTime(ldt, timeOffset);
59  }
60 
71  static OffsetDateTime forEpochSeconds(acetime_t epochSeconds,
73  if (epochSeconds != LocalDate::kInvalidEpochSeconds) {
74  epochSeconds += timeOffset.toSeconds();
75  }
76  auto ldt = LocalDateTime::forEpochSeconds(epochSeconds);
77  return OffsetDateTime(ldt, timeOffset);
78  }
79 
85  static OffsetDateTime forUnixSeconds(acetime_t unixSeconds,
87  acetime_t epochSeconds = (unixSeconds == LocalDate::kInvalidEpochSeconds)
88  ? unixSeconds
89  : unixSeconds - LocalDate::kSecondsSinceUnixEpoch;
90  return forEpochSeconds(epochSeconds, timeOffset);
91  }
92 
112  static OffsetDateTime forDateString(const char* dateString);
113 
121  static OffsetDateTime forDateStringChainable(const char*& dateString);
122 
128  static OffsetDateTime forDateString(const __FlashStringHelper* dateString) {
129  // Copy the F() string into a buffer. Use strncpy_P() because ESP32 and
130  // ESP8266 do not have strlcpy_P(). We need +1 for the '\0' character and
131  // another +1 to determine if the dateString is too long to fit.
132  char buffer[kDateStringLength + 2];
133  strncpy_P(buffer, (const char*) dateString, sizeof(buffer));
134  buffer[kDateStringLength + 1] = 0;
135 
136  // check if the original F() was too long
137  size_t len = strlen(buffer);
138  if (len > kDateStringLength) {
139  return forError();
140  }
141 
142  return forDateString(buffer);
143  }
144 
148  }
149 
151  explicit OffsetDateTime() {}
152 
154  bool isError() const {
155  // Check mTimeOffset first because it's expected to be invalid more often.
156  return mTimeOffset.isError() || mLocalDateTime.isError();
157  }
158 
160  int16_t year() const { return mLocalDateTime.year(); }
161 
163  void year(int16_t year) { mLocalDateTime.year(year); }
164 
170  int8_t yearTiny() const { return mLocalDateTime.yearTiny(); }
171 
177  void yearTiny(int8_t yearTiny) { mLocalDateTime.yearTiny(yearTiny); }
178 
180  uint8_t month() const { return mLocalDateTime.month(); }
181 
183  void month(uint8_t month) { mLocalDateTime.month(month); }
184 
186  uint8_t day() const { return mLocalDateTime.day(); }
187 
189  void day(uint8_t day) { mLocalDateTime.day(day); }
190 
192  uint8_t hour() const { return mLocalDateTime.hour(); }
193 
195  void hour(uint8_t hour) { mLocalDateTime.hour(hour); }
196 
198  uint8_t minute() const { return mLocalDateTime.minute(); }
199 
201  void minute(uint8_t minute) { mLocalDateTime.minute(minute); }
202 
204  uint8_t second() const { return mLocalDateTime.second(); }
205 
207  void second(uint8_t second) { mLocalDateTime.second(second); }
208 
210  uint8_t dayOfWeek() const { return mLocalDateTime.dayOfWeek(); }
211 
213  TimeOffset timeOffset() const { return mTimeOffset; }
214 
216  void timeOffset(TimeOffset timeOffset) { mTimeOffset = timeOffset; }
217 
219  const LocalDateTime& localDateTime() const { return mLocalDateTime; }
220 
222  const LocalDate& localDate() const { return mLocalDateTime.localDate(); }
223 
225  const LocalTime& localTime() const { return mLocalDateTime.localTime(); }
226 
232  acetime_t epochSeconds = toEpochSeconds();
233  return OffsetDateTime::forEpochSeconds(epochSeconds, timeOffset);
234  }
235 
240  acetime_t toEpochDays() const {
242 
243  acetime_t epochDays = mLocalDateTime.localDate().toEpochDays();
244 
245  // Increment or decrement the day count depending on the time offset.
246  acetime_t timeOffset = mLocalDateTime.localTime().toSeconds()
247  - mTimeOffset.toSeconds();
248  if (timeOffset >= 86400) return epochDays + 1;
249  if (timeOffset < 0) return epochDays - 1;
250  return epochDays;
251  }
252 
254  acetime_t toUnixDays() const {
257  }
258 
263  acetime_t toEpochSeconds() const {
265  return mLocalDateTime.toEpochSeconds() - mTimeOffset.toSeconds();
266  }
267 
275  acetime_t toUnixSeconds() const {
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::OffsetDateTime::printTo
void printTo(Print &printer) const
Print OffsetDateTime to 'printer' in ISO 8601 format.
Definition: OffsetDateTime.cpp:11
ace_time::LocalDate::kSecondsSinceUnixEpoch
static const acetime_t kSecondsSinceUnixEpoch
Number of seconds from Unix epoch (1970-01-01 00:00:00Z) to the AceTime epoch (2000-01-01 00:00:00Z).
Definition: LocalDate.h:69
ace_time::OffsetDateTime::toUnixSeconds
acetime_t toUnixSeconds() const
Return the number of seconds from Unix epoch 1970-01-01 00:00:00Z.
Definition: OffsetDateTime.h:275
ace_time::LocalDateTime::dayOfWeek
uint8_t dayOfWeek() const
Return the day of the week, Monday=1, Sunday=7 (per ISO 8601).
Definition: LocalDateTime.h:219
ace_time::OffsetDateTime::forDateString
static OffsetDateTime forDateString(const char *dateString)
Factory method.
Definition: OffsetDateTime.cpp:24
ace_time::LocalDateTime::hour
uint8_t hour() const
Return the hour.
Definition: LocalDateTime.h:201
ace_time::OffsetDateTime::OffsetDateTime
OffsetDateTime()
Constructor.
Definition: OffsetDateTime.h:151
ace_time::LocalDate::kInvalidEpochSeconds
static const acetime_t kInvalidEpochSeconds
Sentinel epochSeconds which indicates an error.
Definition: LocalDate.h:63
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::TimeOffset::forError
static TimeOffset forError()
Return an error indicator.
Definition: TimeOffset.h:105
ace_time::TimeOffset::isError
bool isError() const
Return true if this TimeOffset represents an error.
Definition: TimeOffset.h:138
ace_time::TimeOffset::toSeconds
int32_t toSeconds() const
Return the time offset as seconds.
Definition: TimeOffset.h:116
ace_time::LocalDate::kInvalidEpochDays
static const acetime_t kInvalidEpochDays
Sentinel epochDays which indicates an error.
Definition: LocalDate.h:60
ace_time::OffsetDateTime::second
void second(uint8_t second)
Set the second.
Definition: OffsetDateTime.h:207
ace_time::LocalDate::toEpochDays
acetime_t toEpochDays() const
Return number of days since AceTime epoch (2000-01-01 00:00:00Z).
Definition: LocalDate.h:300
ace_time::OffsetDateTime::localDate
const LocalDate & localDate() const
Return the LocalDate.
Definition: OffsetDateTime.h:222
ace_time::OffsetDateTime::toEpochSeconds
acetime_t toEpochSeconds() const
Return seconds since AceTime epoch (2000-01-01 00:00:00Z), taking into account the offset zone.
Definition: OffsetDateTime.h:263
ace_time::OffsetDateTime::month
uint8_t month() const
Return the month with January=1, December=12.
Definition: OffsetDateTime.h:180
ace_time::OffsetDateTime::day
void day(uint8_t day)
Set the day of the month.
Definition: OffsetDateTime.h:189
ace_time::OffsetDateTime::year
void year(int16_t year)
Set the year.
Definition: OffsetDateTime.h:163
ace_time::LocalDateTime::forError
static LocalDateTime forError()
Factory method that returns an instance where isError() returns true.
Definition: LocalDateTime.h:156
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::OffsetDateTime::forEpochSeconds
static OffsetDateTime forEpochSeconds(acetime_t epochSeconds, TimeOffset timeOffset)
Factory method.
Definition: OffsetDateTime.h:71
ace_time::OffsetDateTime::yearTiny
int8_t yearTiny() const
Return the single-byte year offset from year 2000.
Definition: OffsetDateTime.h:170
ace_time::LocalDate
The date (year, month, day) representing the date without regards to time zone.
Definition: LocalDate.h:36
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:31
ace_time::OffsetDateTime::dayOfWeek
uint8_t dayOfWeek() const
Return the day of the week, Monday=1, Sunday=7 (per ISO 8601).
Definition: OffsetDateTime.h:210
ace_time::OffsetDateTime::convertToTimeOffset
OffsetDateTime convertToTimeOffset(TimeOffset timeOffset) const
Create a OffsetDateTime in a different offset zone code (with the same epochSeconds).
Definition: OffsetDateTime.h:231
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)
Factory method using separated date and time components.
Definition: LocalDateTime.h:43
ace_time::LocalDateTime::month
uint8_t month() const
Return the month with January=1, December=12.
Definition: LocalDateTime.h:189
ace_time::OffsetDateTime::yearTiny
void yearTiny(int8_t yearTiny)
Set the single-byte year offset from year 2000.
Definition: OffsetDateTime.h:177
ace_time::OffsetDateTime
The date (year, month, day), time (hour, minute, second) and offset from UTC (timeOffset).
Definition: OffsetDateTime.h:33
ace_time::OffsetDateTime::forError
static OffsetDateTime forError()
Factory method that returns an instance whose isError() is true.
Definition: OffsetDateTime.h:146
ace_time::OffsetDateTime::second
uint8_t second() const
Return the second.
Definition: OffsetDateTime.h:204
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::LocalDateTime::second
uint8_t second() const
Return the second.
Definition: LocalDateTime.h:213
ace_time::LocalDateTime::localTime
const LocalTime & localTime() const
Return the LocalTime.
Definition: LocalDateTime.h:225
ace_time::OffsetDateTime::toUnixDays
acetime_t toUnixDays() const
Return the number of days since Unix epoch (1970-01-01 00:00:00).
Definition: OffsetDateTime.h:254
ace_time::OffsetDateTime::month
void month(uint8_t month)
Set the month.
Definition: OffsetDateTime.h:183
ace_time::LocalDateTime::isError
bool isError() const
Return true if any component indicates an error condition.
Definition: LocalDateTime.h:164
ace_time::LocalDateTime::minute
uint8_t minute() const
Return the minute.
Definition: LocalDateTime.h:207
ace_time::LocalDateTime::localDate
const LocalDate & localDate() const
Return the LocalDate.
Definition: LocalDateTime.h:222
ace_time::OffsetDateTime::minute
void minute(uint8_t minute)
Set the minute.
Definition: OffsetDateTime.h:201
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::LocalDateTime::toEpochSeconds
acetime_t toEpochSeconds() const
Return seconds since AceTime epoch 2000-01-01 00:00:00Z, after assuming that the date and time compon...
Definition: LocalDateTime.h:246
ace_time::OffsetDateTime::timeOffset
void timeOffset(TimeOffset timeOffset)
Set the offset zone.
Definition: OffsetDateTime.h:216
ace_time::OffsetDateTime::forDateString
static OffsetDateTime forDateString(const __FlashStringHelper *dateString)
Factory method.
Definition: OffsetDateTime.h:128
ace_time::LocalDateTime::year
int16_t year() const
Return the year.
Definition: LocalDateTime.h:169
ace_time::OffsetDateTime::timeOffset
TimeOffset timeOffset() const
Return the offset zone of the OffsetDateTime.
Definition: OffsetDateTime.h:213
ace_time::LocalDateTime::yearTiny
int8_t yearTiny() const
Return the single-byte year offset from year 2000.
Definition: LocalDateTime.h:179
ace_time::OffsetDateTime::hour
void hour(uint8_t hour)
Set the hour.
Definition: OffsetDateTime.h:195
ace_time::OffsetDateTime::day
uint8_t day() const
Return the day of the month.
Definition: OffsetDateTime.h:186
ace_time::OffsetDateTime::minute
uint8_t minute() const
Return the minute.
Definition: OffsetDateTime.h:198
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)
Factory method using separated date, time, and UTC offset fields.
Definition: OffsetDateTime.h:53
ace_time::LocalTime::toSeconds
acetime_t toSeconds() const
Return the number of seconds since midnight.
Definition: LocalTime.h:137
ace_time::OffsetDateTime::forUnixSeconds
static OffsetDateTime forUnixSeconds(acetime_t unixSeconds, TimeOffset timeOffset)
Factory method that takes the number of seconds since Unix Epoch of 1970-01-01.
Definition: OffsetDateTime.h:85
ace_time::LocalDateTime::day
uint8_t day() const
Return the day of the month.
Definition: LocalDateTime.h:195
ace_time::OffsetDateTime::forLocalDateTimeAndOffset
static OffsetDateTime forLocalDateTimeAndOffset(const LocalDateTime &localDateTime, TimeOffset timeOffset)
Factory method from LocalDateTime and TimeOffset.
Definition: OffsetDateTime.h:37
ace_time::OffsetDateTime::isError
bool isError() const
Return true if any component indicates an error condition.
Definition: OffsetDateTime.h:154
ace_time::OffsetDateTime::hour
uint8_t hour() const
Return the hour.
Definition: OffsetDateTime.h:192
ace_time::LocalDate::kDaysSinceUnixEpoch
static const acetime_t kDaysSinceUnixEpoch
Number of days from Unix epoch (1970-01-01 00:00:00Z) to the AceTime epoch (2000-01-01 00:00:00Z).
Definition: LocalDate.h:75
ace_time::OffsetDateTime::localDateTime
const LocalDateTime & localDateTime() const
Return the LocalDateTime.
Definition: OffsetDateTime.h:219
ace_time::OffsetDateTime::localTime
const LocalTime & localTime() const
Return the LocalTime.
Definition: OffsetDateTime.h:225
ace_time::OffsetDateTime::year
int16_t year() const
Return the year.
Definition: OffsetDateTime.h:160
ace_time::LocalDateTime::forEpochSeconds
static LocalDateTime forEpochSeconds(acetime_t epochSeconds)
Factory method.
Definition: LocalDateTime.h:70
ace_time::OffsetDateTime::toEpochDays
acetime_t toEpochDays() const
Return number of whole days since AceTime epoch (2000-01-01 00:00:00Z), taking into account the offse...
Definition: OffsetDateTime.h:240
ace_time::LocalTime
The time (hour, minute, second) fields representing the time without regards to the day or the time z...
Definition: LocalTime.h:26