AceTime  2.2.0
Date and time classes for Arduino that support timezones from the TZ Database.
ZonedExtra.h
1 /*
2  * MIT License
3  * Copyright (c) 2023 Brian T. Park
4  */
5 
6 #ifndef ACE_TIME_ZONED_EXTRA_H
7 #define ACE_TIME_ZONED_EXTRA_H
8 
9 #include <string.h> // memcpy()
10 #include <stdint.h>
11 #include "common/common.h" // acetime_t, kAbbrevSize
12 #include "TimeOffset.h"
13 
14 namespace ace_time {
15 
16 class TimeZone;
17 class LocalDateTime;
18 
19 class ZonedExtra {
20  public:
21  static const int16_t kInvalidMinutes = INT16_MIN;
22 
28  static const uint8_t kTypeNotFound = 0;
29 
34  static const uint8_t kTypeExact = 1;
35 
42  static const uint8_t kTypeGap = 2;
43 
51  static const uint8_t kTypeOverlap = 3;
52 
54  static ZonedExtra forError() {
55  return ZonedExtra();
56  }
57 
64  int16_t year, uint8_t month, uint8_t day,
65  uint8_t hour, uint8_t minute, uint8_t second,
66  const TimeZone& tz, uint8_t fold = 0);
67 
70  acetime_t epochSeconds,
71  const TimeZone& tz);
72 
79  const LocalDateTime& ldt,
80  const TimeZone& tz);
81 
83  explicit ZonedExtra() {}
84 
86  explicit ZonedExtra(
87  uint8_t type,
88  int16_t stdOffsetMinutes,
89  int16_t dstOffsetMinutes,
90  int16_t reqStdOffsetMinutes,
91  int16_t reqDstOffsetMinutes,
92  const char* abbrev)
93  : mStdOffsetMinutes(stdOffsetMinutes)
94  , mDstOffsetMinutes(dstOffsetMinutes)
95  , mReqStdOffsetMinutes(reqStdOffsetMinutes)
96  , mReqDstOffsetMinutes(reqDstOffsetMinutes)
97  , mType(type)
98  {
99  memcpy(mAbbrev, abbrev, internal::kAbbrevSize);
100  mAbbrev[internal::kAbbrevSize - 1] = '\0';
101  }
102 
104  bool isError() const {
105  return mStdOffsetMinutes == kInvalidMinutes;
106  }
107 
108  uint8_t type() const { return mType; }
109 
112  return TimeOffset::forMinutes(mStdOffsetMinutes);
113  }
114 
117  return TimeOffset::forMinutes(mDstOffsetMinutes);
118  }
119 
127  return TimeOffset::forMinutes(mStdOffsetMinutes + mDstOffsetMinutes);
128  }
129 
135  return TimeOffset::forMinutes(mReqStdOffsetMinutes);
136  }
137 
143  return TimeOffset::forMinutes(mReqDstOffsetMinutes);
144  }
145 
155  return TimeOffset::forMinutes(
156  mReqStdOffsetMinutes + mReqDstOffsetMinutes);
157  }
158 
165  const char* abbrev() const { return mAbbrev; }
166 
167  private:
168  int16_t mStdOffsetMinutes = kInvalidMinutes;
169  int16_t mDstOffsetMinutes = kInvalidMinutes;
170  int16_t mReqStdOffsetMinutes = kInvalidMinutes;
171  int16_t mReqDstOffsetMinutes = kInvalidMinutes;
172  uint8_t mType = kTypeNotFound;
173  char mAbbrev[internal::kAbbrevSize] = "";
174 };
175 
176 }
177 
178 #endif
Class that holds the date-time as the components (year, month, day, hour, minute, second) without reg...
Definition: LocalDateTime.h:31
A thin wrapper that represents a time offset from a reference point, usually 00:00 at UTC,...
Definition: TimeOffset.h:56
static TimeOffset forMinutes(int16_t minutes)
Create TimeOffset from minutes from 00:00.
Definition: TimeOffset.h:83
Class that describes a time zone.
Definition: TimeZone.h:85
TimeOffset reqDstOffset() const
DST offset of the requested epochSeconds or LocalDateTime.
Definition: ZonedExtra.h:142
TimeOffset reqStdOffset() const
STD offset of the requested epochSeconds or LocalDateTime.
Definition: ZonedExtra.h:134
static ZonedExtra forError()
Return an instance that indicates an error.
Definition: ZonedExtra.h:54
static ZonedExtra forLocalDateTime(const LocalDateTime &ldt, const TimeZone &tz)
Return an instance for the given LocalDateTime and TimeZone.
Definition: ZonedExtra.cpp:23
TimeOffset stdOffset() const
STD offset of the resulting OffsetDateTime.
Definition: ZonedExtra.h:111
static ZonedExtra forComponents(int16_t year, uint8_t month, uint8_t day, uint8_t hour, uint8_t minute, uint8_t second, const TimeZone &tz, uint8_t fold=0)
Return an instance for the given LocalDateTime and TimeZone.
Definition: ZonedExtra.cpp:6
static const uint8_t kTypeNotFound
The epochSeconds or LocalDateTime was not found because it was outside the range of the zoneinfo data...
Definition: ZonedExtra.h:28
static const uint8_t kTypeOverlap
The given LocalDateTime matches 2 possible epochSeconds, which is disambguiated by the LocalDateTime:...
Definition: ZonedExtra.h:51
TimeOffset dstOffset() const
DST offset of the resulting OffsetDateTime.
Definition: ZonedExtra.h:116
ZonedExtra()
Consructor.
Definition: ZonedExtra.h:83
TimeOffset reqTimeOffset() const
The total time offset of the requested epochSeconds of LocalDateTime, (reqStdOffset + reqDstOffset).
Definition: ZonedExtra.h:154
static const uint8_t kTypeExact
The given LocalDateTime matches a single epochSeconds.
Definition: ZonedExtra.h:34
const char * abbrev() const
Returns the pointer to the local string buffer containing the timezone abbreviation (e....
Definition: ZonedExtra.h:165
static const uint8_t kTypeGap
The given LocalDateTime occurs in a gap and does not match any epochSeconds.
Definition: ZonedExtra.h:42
static ZonedExtra forEpochSeconds(acetime_t epochSeconds, const TimeZone &tz)
Return an instance for the given epochSeconds and TimeZone.
Definition: ZonedExtra.cpp:16
bool isError() const
Indicates that the LocalDateTime or epochSeconds was not found.
Definition: ZonedExtra.h:104
TimeOffset timeOffset() const
The total time offset (stdOffset + dstOffset).
Definition: ZonedExtra.h:126
ZonedExtra(uint8_t type, int16_t stdOffsetMinutes, int16_t dstOffsetMinutes, int16_t reqStdOffsetMinutes, int16_t reqDstOffsetMinutes, const char *abbrev)
Consructor.
Definition: ZonedExtra.h:86
Identifiers used by implementation code which need to be publically exported.
int32_t acetime_t
Type for the number of seconds from epoch.
Definition: common.h:24