3 /// Timezone adjustment class, wrapping the TZ environment
4 /// variable to make struct tm -> time_t conversions easier.
8 Copyright (C) 2010, Chris Frey <cdfrey@foursquare.net>, To God be the glory
9 Released to the public domain.
10 Included in Barry and Barrified the namespace July 2010
13 #ifndef __TZWRAPPER_H__
20 namespace Barry
{ namespace Sync
{
22 /// Parses ISO timestamp in the format of YYYYMMDDTHHMMSS[Z]
23 /// and places broken down time in result.
24 /// The trailing Z is optional in the format.
25 /// If the Z exists, utc will be set to true, otherwise false.
26 /// Returns NULL on error.
28 BXEXPORT
struct tm
* iso_to_tm(const char *timestamp
,
32 /// Turns the struct tm into an ISO timestamp in the format
33 /// of YYYYMMDDTHHMMSS[Z]. The Z is appended if utc is true.
34 /// This function assumes that t contains sane values, and will
35 /// create the target string directly from its content.
36 /// Returns the ISO timestamp, or empty string on error.
37 /// If t contains sane values, this function should never fail.
39 BXEXPORT
std::string
tm_to_iso(const struct tm
*t
, bool utc
);
41 /// utc_mktime() converts a struct tm that contains
42 /// broken down time in utc to a time_t. This function uses
43 /// a brute-force method of conversion that does not require
44 /// the environment variable TZ to be changed at all, and is
45 /// therefore slightly more thread-safe in that regard.
47 /// The difference between mktime() and utc_mktime() is that
48 /// standard mktime() expects the struct tm to be in localtime,
49 /// according to the current TZ and system setting, while utc_mktime()
50 /// always assumes that the struct tm is in UTC, and converts it
51 /// to time_t regardless of what TZ is currently set.
53 /// The difference between utc_mktime() and TzWrapper::iso_mktime()
54 /// is that iso_mktime() will parse straight from an ISO string,
55 /// and if the ISO timestamp ends in a 'Z', it will behave like
56 /// utc_mktime() except it will alter the TZ environment variable
57 /// to do it. If the ISO timestamp has no 'Z', then iso_mktime()
58 /// behaves like mktime().
60 BXEXPORT
time_t utc_mktime(struct tm
*utctime
);
65 /// Wrapper class for the TZ environment variable. This class allows
66 /// setting TZ to any number of variables, and will restore the original
67 /// setting on destruction.
69 /// By default, TzWrapper does not change the environment at all, but
70 /// only saves it. Alternately, you can use the timezone constructor
71 /// to save and set a new timezone on the fly.
73 /// Each Set() and Unset() function returns a reference to TzWrapper,
74 /// so that you can chain function calls like this:
76 /// time_t utc = TzWrapper("Canada/Pacific").mktime(&pacific_tm);
78 /// In addition, there are two static utility functions used to
79 /// convert ISO timestamps to struct tm* and time_t values.
81 /// Note: This class is not thread-safe, since it modifies the TZ
82 /// environment variable without locking. If other threads
83 /// use time functions, this may interfere with their behaviour.
85 class BXEXPORT TzWrapper
87 std::string m_orig_tz
;
94 char *ptz
= getenv("TZ");
104 Set(m_orig_tz
.c_str());
113 /// Does not change TZ, only saves current setting
120 /// Saves current setting and sets TZ to new timezone value.
121 /// If timezone is null, it is the same as calling Unset().
122 explicit TzWrapper(const char *timezone
)
134 /// Set TZ to a new value. If timezone is null, it is the
135 /// same as calling Unset().
137 /// If timezone is an empty or invalid timezone string, it
138 /// is the same as calling SetUTC().
139 TzWrapper
& Set(const char *timezone
)
142 setenv("TZ", timezone
, 1);
150 /// Deletes TZ from the environment, which has the same effect
151 /// as calling SetSysLocal(). This is not a permanent
152 /// condition, since TZ will be restored to original state
153 /// upon destruction.
162 /// Set timezone to UTC
168 /// Use system localtime. This overrides any TZ value that the
169 /// user may have set before running your program.
170 TzWrapper
& SetSysLocal()
175 /// Use the default TZ value that the user set before running
176 /// this program. In most cases, this will be the user's
177 /// preferred local timezone.
178 TzWrapper
& SetDefault()
183 /// Same as SetDefault()
190 // C library wrappers, for calls like:
191 // time_t t = TzWrapper("Canada/Pacific").mktime(tm);
193 char* asctime(const struct tm
*t
) const { return ::asctime(t
); }
194 char* asctime_r(const struct tm
*t
, char *buf
) const
195 { return ::asctime_r(t
, buf
); }
196 char* ctime(const time_t *t
) const { return ::ctime(t
); }
197 char* ctime_r(const time_t *t
, char *buf
) const
198 { return ::ctime_r(t
, buf
); }
199 struct tm
* gmtime(const time_t *t
) const { return ::gmtime(t
); }
200 struct tm
* gmtime_r(const time_t *t
, struct tm
*result
) const
201 { return ::gmtime_r(t
, result
); }
202 struct tm
* localtime(const time_t *t
) const { return ::localtime(t
); }
203 struct tm
* localtime_r(const time_t *t
, struct tm
*result
) const
204 { return ::localtime_r(t
, result
); }
205 time_t mktime(struct tm
*t
) { return ::mktime(t
); }
208 // Additional utility functions
211 /// Converts an ISO timestamp (YYYYMMDDTHHMMWW[Z]) into a
212 /// unix time_t. If the 'Z' UTC flag is not specified, then
213 /// the timestamp will be assumed to be in the current
214 /// default timezone. Otherwise, SetUTC() will be used for the
217 /// This function uses an internal TzWrapper to adjust TZ
218 /// if necessary, which is why it is a static function
219 /// of TzWrapper, instead of a standalone function.
221 static time_t iso_mktime(const char *timestamp
);
224 }} // namespace Barry::Sync