AceTime 3.0.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> // strncpy()
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:
22 static const uint8_t kAbbrevSize = ace_time::kAbbrevSize;
23
29 static const uint8_t kTypeNotFound = 0;
30
35 static const uint8_t kTypeExact = 1;
36
43 static const uint8_t kTypeGap = 2;
44
52 static const uint8_t kTypeOverlap = 3;
53
55 static ZonedExtra forError() {
56 return ZonedExtra();
57 }
58
64 static ZonedExtra forComponents(
65 int16_t year, uint8_t month, uint8_t day,
66 uint8_t hour, uint8_t minute, uint8_t second,
67 const TimeZone& tz, uint8_t fold = 0);
68
70 static ZonedExtra forEpochSeconds(
71 acetime_t epochSeconds,
72 const TimeZone& tz);
73
79 static ZonedExtra forLocalDateTime(
80 const LocalDateTime& ldt,
81 const TimeZone& tz);
82
84 explicit ZonedExtra() {}
85
87 explicit ZonedExtra(
88 uint8_t type,
89 int32_t stdOffsetSeconds,
90 int32_t dstOffsetSeconds,
91 int32_t reqStdOffsetSeconds,
92 int32_t reqDstOffsetSeconds,
93 const char* abbrev)
94 : mStdOffsetSeconds(stdOffsetSeconds)
95 , mDstOffsetSeconds(dstOffsetSeconds)
96 , mReqStdOffsetSeconds(reqStdOffsetSeconds)
97 , mReqDstOffsetSeconds(reqDstOffsetSeconds)
98 , mType(type)
99 {
100 strncpy(mAbbrev, abbrev, kAbbrevSize - 1);
101 mAbbrev[kAbbrevSize - 1] = '\0';
102 }
103
105 bool isError() const {
106 return mStdOffsetSeconds == kInvalidSeconds;
107 }
108
109 uint8_t type() const { return mType; }
110
112 TimeOffset stdOffset() const {
113 return TimeOffset::forSeconds(mStdOffsetSeconds);
114 }
115
117 TimeOffset dstOffset() const {
118 return TimeOffset::forSeconds(mDstOffsetSeconds);
119 }
120
127 TimeOffset timeOffset() const {
128 return TimeOffset::forSeconds(mStdOffsetSeconds + mDstOffsetSeconds);
129 }
130
135 TimeOffset reqStdOffset() const {
136 return TimeOffset::forSeconds(mReqStdOffsetSeconds);
137 }
138
143 TimeOffset reqDstOffset() const {
144 return TimeOffset::forSeconds(mReqDstOffsetSeconds);
145 }
146
155 TimeOffset reqTimeOffset() const {
156 return TimeOffset::forSeconds(
157 mReqStdOffsetSeconds + mReqDstOffsetSeconds);
158 }
159
166 const char* abbrev() const { return mAbbrev; }
167
168 private:
169 static const int32_t kInvalidSeconds = INT32_MIN;
170
171 int32_t mStdOffsetSeconds = kInvalidSeconds;
172 int32_t mDstOffsetSeconds = kInvalidSeconds;
173 int32_t mReqStdOffsetSeconds = kInvalidSeconds;
174 int32_t mReqDstOffsetSeconds = kInvalidSeconds;
175 uint8_t mType = kTypeNotFound;
176 char mAbbrev[kAbbrevSize] = "";
177 };
178
179 }
180
181 #endif
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
A thin wrapper that represents a time offset from a reference point, usually 00:00 at UTC,...
Definition: TimeOffset.h:56
ace_time::TimeOffset::forSeconds
static TimeOffset forSeconds(int32_t seconds)
Create TimeOffset from seconds from 00:00.
Definition: TimeOffset.h:96
ace_time::TimeZone
Class that describes a time zone.
Definition: TimeZone.h:86
ace_time::ZonedExtra
Definition: ZonedExtra.h:19
ace_time::ZonedExtra::reqDstOffset
TimeOffset reqDstOffset() const
DST offset of the requested epochSeconds or LocalDateTime.
Definition: ZonedExtra.h:143
ace_time::ZonedExtra::reqStdOffset
TimeOffset reqStdOffset() const
STD offset of the requested epochSeconds or LocalDateTime.
Definition: ZonedExtra.h:135
ace_time::ZonedExtra::forError
static ZonedExtra forError()
Return an instance that indicates an error.
Definition: ZonedExtra.h:55
ace_time::ZonedExtra::forLocalDateTime
static ZonedExtra forLocalDateTime(const LocalDateTime &ldt, const TimeZone &tz)
Return an instance for the given LocalDateTime and TimeZone.
Definition: ZonedExtra.cpp:23
ace_time::ZonedExtra::stdOffset
TimeOffset stdOffset() const
STD offset of the resulting OffsetDateTime.
Definition: ZonedExtra.h:112
ace_time::ZonedExtra::kAbbrevSize
static const uint8_t kAbbrevSize
Size of char buffer needed to hold the largest abbreviation.
Definition: ZonedExtra.h:22
ace_time::ZonedExtra::forComponents
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
ace_time::ZonedExtra::kTypeNotFound
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:29
ace_time::ZonedExtra::kTypeOverlap
static const uint8_t kTypeOverlap
The given LocalDateTime matches 2 possible epochSeconds, which is disambguiated by the LocalDateTime:...
Definition: ZonedExtra.h:52
ace_time::ZonedExtra::dstOffset
TimeOffset dstOffset() const
DST offset of the resulting OffsetDateTime.
Definition: ZonedExtra.h:117
ace_time::ZonedExtra::ZonedExtra
ZonedExtra()
Consructor.
Definition: ZonedExtra.h:84
ace_time::ZonedExtra::reqTimeOffset
TimeOffset reqTimeOffset() const
The total time offset of the requested epochSeconds of LocalDateTime, (reqStdOffset + reqDstOffset).
Definition: ZonedExtra.h:155
ace_time::ZonedExtra::kTypeExact
static const uint8_t kTypeExact
The given LocalDateTime matches a single epochSeconds.
Definition: ZonedExtra.h:35
ace_time::ZonedExtra::abbrev
const char * abbrev() const
Returns the pointer to the local string buffer containing the timezone abbreviation (e....
Definition: ZonedExtra.h:166
ace_time::ZonedExtra::kTypeGap
static const uint8_t kTypeGap
The given LocalDateTime occurs in a gap and does not match any epochSeconds.
Definition: ZonedExtra.h:43
ace_time::ZonedExtra::ZonedExtra
ZonedExtra(uint8_t type, int32_t stdOffsetSeconds, int32_t dstOffsetSeconds, int32_t reqStdOffsetSeconds, int32_t reqDstOffsetSeconds, const char *abbrev)
Consructor.
Definition: ZonedExtra.h:87
ace_time::ZonedExtra::forEpochSeconds
static ZonedExtra forEpochSeconds(acetime_t epochSeconds, const TimeZone &tz)
Return an instance for the given epochSeconds and TimeZone.
Definition: ZonedExtra.cpp:16
ace_time::ZonedExtra::isError
bool isError() const
Indicates that the LocalDateTime or epochSeconds was not found.
Definition: ZonedExtra.h:105
ace_time::ZonedExtra::timeOffset
TimeOffset timeOffset() const
The total time offset (stdOffset + dstOffset).
Definition: ZonedExtra.h:127
common.h
Identifiers used by implementation code which need to be publically exported.
ace_time::kAbbrevSize
const uint8_t kAbbrevSize
Size of the c-string buffer needed to hold a time zone abbreviation.
Definition: common.h:44
ace_time::acetime_t
int32_t acetime_t
Type for the number of seconds from epoch.
Definition: common.h:24