AceTime  0.3
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 #ifndef ACE_TIME_OFFSET_DATE_TIME_H
2 #define ACE_TIME_OFFSET_DATE_TIME_H
3 
4 #include <stdint.h>
5 #include "TimeOffset.h"
6 #include "LocalDateTime.h"
7 
8 class Print;
9 
10 namespace ace_time {
11 
32  public:
33 
37  return OffsetDateTime(localDateTime, timeOffset);
38  }
39 
51  static OffsetDateTime forComponents(int16_t year, uint8_t month, uint8_t
52  day, uint8_t hour, uint8_t minute, uint8_t second, TimeOffset
53  timeOffset) {
54  auto ldt = LocalDateTime::forComponents(year, month, day, hour, minute,
55  second);
56  return OffsetDateTime(ldt, timeOffset);
57  }
58 
69  static OffsetDateTime forEpochSeconds(acetime_t epochSeconds,
71  if (epochSeconds != LocalDate::kInvalidEpochSeconds) {
72  epochSeconds += timeOffset.toSeconds();
73  }
74  auto ldt = LocalDateTime::forEpochSeconds(epochSeconds);
75  return OffsetDateTime(ldt, timeOffset);
76  }
77 
83  static OffsetDateTime forUnixSeconds(acetime_t unixSeconds,
85  acetime_t epochSeconds = (unixSeconds == LocalDate::kInvalidEpochSeconds)
86  ? unixSeconds
87  : unixSeconds - LocalDate::kSecondsSinceUnixEpoch;
88  return forEpochSeconds(epochSeconds, timeOffset);
89  }
90 
110  static OffsetDateTime forDateString(const char* dateString);
111 
119  static OffsetDateTime forDateStringChainable(const char*& dateString);
120 
126  static OffsetDateTime forDateString(const __FlashStringHelper* dateString) {
127  // Copy the F() string into a buffer. Use strncpy_P() because ESP32 and
128  // ESP8266 do not have strlcpy_P(). We need +1 for the '\0' character and
129  // another +1 to determine if the dateString is too long to fit.
130  char buffer[kDateStringLength + 2];
131  strncpy_P(buffer, (const char*) dateString, sizeof(buffer));
132  buffer[kDateStringLength + 1] = 0;
133 
134  // check if the original F() was too long
135  size_t len = strlen(buffer);
136  if (len > kDateStringLength) {
137  return forError();
138  }
139 
140  return forDateString(buffer);
141  }
142 
146  }
147 
149  explicit OffsetDateTime() {}
150 
152  bool isError() const {
153  // Check mTimeOffset first because it's expected to be invalid more often.
154  return mTimeOffset.isError() || mLocalDateTime.isError();
155  }
156 
158  int16_t year() const { return mLocalDateTime.year(); }
159 
161  void year(int16_t year) { mLocalDateTime.year(year); }
162 
164  int8_t yearTiny() const { return mLocalDateTime.yearTiny(); }
165 
167  void yearTiny(int8_t yearTiny) { mLocalDateTime.yearTiny(yearTiny); }
168 
170  uint8_t month() const { return mLocalDateTime.month(); }
171 
173  void month(uint8_t month) { mLocalDateTime.month(month); }
174 
176  uint8_t day() const { return mLocalDateTime.day(); }
177 
179  void day(uint8_t day) { mLocalDateTime.day(day); }
180 
182  uint8_t hour() const { return mLocalDateTime.hour(); }
183 
185  void hour(uint8_t hour) { mLocalDateTime.hour(hour); }
186 
188  uint8_t minute() const { return mLocalDateTime.minute(); }
189 
191  void minute(uint8_t minute) { mLocalDateTime.minute(minute); }
192 
194  uint8_t second() const { return mLocalDateTime.second(); }
195 
197  void second(uint8_t second) { mLocalDateTime.second(second); }
198 
200  uint8_t dayOfWeek() const { return mLocalDateTime.dayOfWeek(); }
201 
203  TimeOffset timeOffset() const { return mTimeOffset; }
204 
206  void timeOffset(TimeOffset timeOffset) { mTimeOffset = timeOffset; }
207 
209  const LocalDateTime& localDateTime() const { return mLocalDateTime; }
210 
212  const LocalDate& localDate() const { return mLocalDateTime.localDate(); }
213 
215  const LocalTime& localTime() const { return mLocalDateTime.localTime(); }
216 
222  acetime_t epochSeconds = toEpochSeconds();
223  return OffsetDateTime::forEpochSeconds(epochSeconds, timeOffset);
224  }
225 
230  acetime_t toEpochDays() const {
232 
233  acetime_t epochDays = mLocalDateTime.localDate().toEpochDays();
234 
235  // Increment or decrement the day count depending on the time offset.
236  acetime_t timeOffset = mLocalDateTime.localTime().toSeconds()
237  - mTimeOffset.toSeconds();
238  if (timeOffset >= 86400) return epochDays + 1;
239  if (timeOffset < 0) return epochDays - 1;
240  return epochDays;
241  }
242 
244  acetime_t toUnixDays() const {
247  }
248 
253  acetime_t toEpochSeconds() const {
255  return mLocalDateTime.toEpochSeconds() - mTimeOffset.toSeconds();
256  }
257 
265  acetime_t toUnixSeconds() const {
268  }
269 
276  int8_t compareTo(const OffsetDateTime& that) const {
277  acetime_t thisSeconds = toEpochSeconds();
278  acetime_t thatSeconds = that.toEpochSeconds();
279  if (thisSeconds < thatSeconds) return -1;
280  if (thisSeconds > thatSeconds) return 1;
281  return 0;
282  }
283 
289  void printTo(Print& printer) const;
290 
291  // Use default copy constructor and assignment operator.
292  OffsetDateTime(const OffsetDateTime&) = default;
293  OffsetDateTime& operator=(const OffsetDateTime&) = default;
294 
295  private:
296  friend bool operator==(const OffsetDateTime& a, const OffsetDateTime& b);
297 
299  static const uint8_t kDateStringLength = 25;
300 
302  explicit OffsetDateTime(const LocalDateTime& ldt, TimeOffset timeOffset):
303  mLocalDateTime(ldt),
304  mTimeOffset(timeOffset) {}
305 
306  LocalDateTime mLocalDateTime;
307  TimeOffset mTimeOffset;
308 };
309 
315 inline bool operator==(const OffsetDateTime& a, const OffsetDateTime& b) {
316  return a.mLocalDateTime == b.mLocalDateTime
317  && a.mTimeOffset == b.mTimeOffset;
318 }
319 
321 inline bool operator!=(const OffsetDateTime& a, const OffsetDateTime& b) {
322  return ! (a == b);
323 }
324 
325 }
326 
327 #endif
acetime_t toSeconds() const
Return the number of seconds since midnight.
Definition: LocalTime.h:131
const LocalTime & localTime() const
Return the LocalTime.
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:51
static TimeOffset forError()
Return an error indicator.
Definition: TimeOffset.h:105
uint8_t minute() const
Return the minute.
int16_t year() const
Return the year.
uint8_t minute() const
Return the minute.
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:57
uint8_t second() const
Return the second.
void minute(uint8_t minute)
Set the minute.
static const acetime_t kInvalidEpochDays
Sentinel epochDays which indicates an error.
Definition: LocalDate.h:42
int8_t yearTiny() const
Return the single-byte year offset from year 2000.
void day(uint8_t day)
Set the day of the month.
acetime_t toEpochDays() const
Return number of whole days since AceTime epoch (2000-01-01 00:00:00Z), taking into account the offse...
static const acetime_t kInvalidEpochSeconds
Sentinel epochSeconds which indicates an error.
Definition: LocalDate.h:45
The time (hour, minute, second) fields representing the time without regards to the day or the time z...
Definition: LocalTime.h:20
uint8_t dayOfWeek() const
Return the day of the week, Monday=1, Sunday=7 (per ISO 8601).
bool isError() const
Return true if this TimeOffset represents an error.
Definition: TimeOffset.h:150
OffsetDateTime convertToTimeOffset(TimeOffset timeOffset) const
Create a OffsetDateTime in a different offset zone code (with the same epochSeconds).
acetime_t toEpochDays() const
Return number of days since AceTime epoch (2000-01-01 00:00:00Z).
Definition: LocalDate.h:274
uint8_t month() const
Return the month with January=1, December=12.
static OffsetDateTime forLocalDateTimeAndOffset(const LocalDateTime &localDateTime, TimeOffset timeOffset)
Factory method from LocalDateTime and TimeOffset.
int32_t toSeconds() const
Return the time offset as seconds.
Definition: TimeOffset.h:128
uint8_t hour() const
Return the hour.
uint8_t day() const
Return the day of the month.
int8_t yearTiny() const
Return the single-byte year offset from year 2000.
static LocalDateTime forEpochSeconds(acetime_t epochSeconds)
Factory method.
Definition: LocalDateTime.h:53
acetime_t toUnixSeconds() const
Return the number of seconds from Unix epoch 1970-01-01 00:00:00Z.
void year(int16_t year)
Set the year.
void printTo(Print &printer) const
Print OffsetDateTime to &#39;printer&#39; in ISO 8601 format.
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.
int8_t compareTo(const OffsetDateTime &that) const
Compare this OffsetDateTime with another OffsetDateTime, and return (<0, 0, >0) according to whether ...
OffsetDateTime()
Constructor.
void second(uint8_t second)
Set the second.
uint8_t month() const
Return the month with January=1, December=12.
static OffsetDateTime forEpochSeconds(acetime_t epochSeconds, TimeOffset timeOffset)
Factory method.
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:26
acetime_t toEpochSeconds() const
Return seconds since AceTime epoch 2000-01-01 00:00:00Z, after assuming that the date and time compon...
void timeOffset(TimeOffset timeOffset)
Set the offset zone.
void yearTiny(int8_t yearTiny)
Set the single-byte year offset from year 2000.
const LocalDate & localDate() const
Return the LocalDate.
friend bool operator==(const OffsetDateTime &a, const OffsetDateTime &b)
Return true if two OffsetDateTime objects are equal in all components.
TimeOffset timeOffset() const
Return the offset zone of the OffsetDateTime.
const LocalTime & localTime() const
Return the LocalTime.
void month(uint8_t month)
Set the month.
static OffsetDateTime forDateString(const __FlashStringHelper *dateString)
Factory method.
acetime_t toUnixDays() const
Return the number of days since Unix epoch (1970-01-01 00:00:00).
uint8_t hour() const
Return the hour.
int16_t year() const
Return the year.
const LocalDateTime & localDateTime() const
Return the LocalDateTime.
uint8_t dayOfWeek() const
Return the day of the week, Monday=1, Sunday=7 (per ISO 8601).
The date (year, month, day) and time (hour, minute, second) fields representing the time with an offs...
uint8_t second() const
Return the second.
acetime_t toEpochSeconds() const
Return seconds since AceTime epoch (2000-01-01 00:00:00Z), taking into account the offset zone...
A thin wrapper that represents a time offset from a reference point, usually 00:00 at UTC...
Definition: TimeOffset.h:53
static LocalDateTime forError()
Factory method that returns an instance where isError() returns true.
The date (year, month, day) representing the date without regards to time zone.
Definition: LocalDate.h:30
void hour(uint8_t hour)
Set the hour.
const LocalDate & localDate() const
Return the LocalDate.
static OffsetDateTime forDateStringChainable(const char *&dateString)
Variant of forDateString() that updates the pointer to the next unprocessed character.
uint8_t day() const
Return the day of the month.
static OffsetDateTime forUnixSeconds(acetime_t unixSeconds, TimeOffset timeOffset)
Factory method that takes the number of seconds since Unix Epoch of 1970-01-01.
bool isError() const
Return true if any component indicates an error condition.
bool isError() const
Return true if any component indicates an error condition.
static OffsetDateTime forError()
Factory method that returns an instance whose isError() is true.
static OffsetDateTime forDateString(const char *dateString)
Factory method.