<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<title>Barry: tzwrapper.h Source File</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<link href="doxygen.css" rel="stylesheet" type="text/css"/>
</head>
<body>
<!-- Generated by Doxygen 1.6.2-20100208 -->
<div class="navigation" id="top">
<div class="tabs">
<ul>
<li><a href="index.html"><span>Main Page</span></a></li>
<li><a href="modules.html"><span>Modules</span></a></li>
<li><a href="namespaces.html"><span>Namespaces</span></a></li>
<li><a href="annotated.html"><span>Classes</span></a></li>
<li class="current"><a href="files.html"><span>Files</span></a></li>
<li><a href="dirs.html"><span>Directories</span></a></li>
</ul>
</div>
<div class="tabs">
<ul>
<li><a href="files.html"><span>File List</span></a></li>
</ul>
</div>
<div class="navpath"><a class="el" href="dir_65781e9408669bb8d7d9c025fdb5fe86.html">src</a>
</div>
</div>
<div class="contents">
<h1>tzwrapper.h</h1><a href="tzwrapper_8h.html">Go to the documentation of this file.</a><div class="fragment"><pre class="fragment"><a name="l00001"></a>00001 <span class="comment">///</span>
<a name="l00002"></a>00002 <span class="comment"></span><span class="comment">/// \file tzwrapper.h</span>
<a name="l00003"></a>00003 <span class="comment"></span><span class="comment">/// Timezone adjustment class, wrapping the TZ environment</span>
<a name="l00004"></a>00004 <span class="comment"></span><span class="comment">/// variable to make struct tm -> time_t conversions easier.</span>
<a name="l00005"></a>00005 <span class="comment"></span><span class="comment">///</span>
<a name="l00006"></a>00006 <span class="comment"></span>
<a name="l00007"></a>00007 <span class="comment">/*</span>
<a name="l00008"></a>00008 <span class="comment"> Copyright (C) 2010, Chris Frey <cdfrey@foursquare.net>, To God be the glory</span>
<a name="l00009"></a>00009 <span class="comment"> Released to the public domain.</span>
<a name="l00010"></a>00010 <span class="comment"> Included in Barry and Barrified the namespace July 2010</span>
<a name="l00011"></a>00011 <span class="comment">*/</span>
<a name="l00012"></a>00012
<a name="l00013"></a>00013 <span class="preprocessor">#ifndef __TZWRAPPER_H__</span>
<a name="l00014"></a>00014 <span class="preprocessor"></span>
<a name="l00015"></a>00015 <span class="preprocessor">#include "<a class="code" href="dll_8h.html" title="Macros for handling DLL/library API visibility.">dll.h</a>"</span>
<a name="l00016"></a>00016 <span class="preprocessor">#include <string></span>
<a name="l00017"></a>00017 <span class="preprocessor">#include <<a class="code" href="time_8h.html" title="Time related conversion routines.">time.h</a>></span>
<a name="l00018"></a>00018 <span class="preprocessor">#include <stdlib.h></span>
<a name="l00019"></a>00019
<a name="l00020"></a>00020 <span class="keyword">namespace </span>Barry { <span class="keyword">namespace </span>Sync {
<a name="l00021"></a>00021 <span class="comment"></span>
<a name="l00022"></a>00022 <span class="comment">/// Parses ISO timestamp in the format of YYYYMMDDTHHMMSS[Z]</span>
<a name="l00023"></a>00023 <span class="comment">/// and places broken down time in result.</span>
<a name="l00024"></a>00024 <span class="comment">/// The trailing Z is optional in the format.</span>
<a name="l00025"></a>00025 <span class="comment">/// If the Z exists, utc will be set to true, otherwise false.</span>
<a name="l00026"></a>00026 <span class="comment">/// Returns NULL on error.</span>
<a name="l00027"></a>00027 <span class="comment">/// Thread-safe.</span>
<a name="l00028"></a>00028 <span class="comment"></span>BXEXPORT <span class="keyword">struct </span>tm* iso_to_tm(<span class="keyword">const</span> <span class="keywordtype">char</span> *timestamp,
<a name="l00029"></a>00029 <span class="keyword">struct</span> tm *result,
<a name="l00030"></a>00030 <span class="keywordtype">bool</span> &utc);
<a name="l00031"></a>00031 <span class="comment"></span>
<a name="l00032"></a>00032 <span class="comment">/// Turns the struct tm into an ISO timestamp in the format</span>
<a name="l00033"></a>00033 <span class="comment">/// of YYYYMMDDTHHMMSS[Z]. The Z is appended if utc is true.</span>
<a name="l00034"></a>00034 <span class="comment">/// This function assumes that t contains sane values, and will</span>
<a name="l00035"></a>00035 <span class="comment">/// create the target string directly from its content.</span>
<a name="l00036"></a>00036 <span class="comment">/// Returns the ISO timestamp, or empty string on error.</span>
<a name="l00037"></a>00037 <span class="comment">/// If t contains sane values, this function should never fail.</span>
<a name="l00038"></a>00038 <span class="comment">/// Thread-safe.</span>
<a name="l00039"></a>00039 <span class="comment"></span>BXEXPORT std::string tm_to_iso(<span class="keyword">const</span> <span class="keyword">struct</span> tm *t, <span class="keywordtype">bool</span> utc);
<a name="l00040"></a>00040 <span class="comment"></span>
<a name="l00041"></a>00041 <span class="comment">/// utc_mktime() converts a struct tm that contains</span>
<a name="l00042"></a>00042 <span class="comment">/// broken down time in utc to a time_t. This function uses</span>
<a name="l00043"></a>00043 <span class="comment">/// a brute-force method of conversion that does not require</span>
<a name="l00044"></a>00044 <span class="comment">/// the environment variable TZ to be changed at all, and is</span>
<a name="l00045"></a>00045 <span class="comment">/// therefore slightly more thread-safe in that regard.</span>
<a name="l00046"></a>00046 <span class="comment">///</span>
<a name="l00047"></a>00047 <span class="comment">/// The difference between mktime() and utc_mktime() is that</span>
<a name="l00048"></a>00048 <span class="comment">/// standard mktime() expects the struct tm to be in localtime,</span>
<a name="l00049"></a>00049 <span class="comment">/// according to the current TZ and system setting, while utc_mktime()</span>
<a name="l00050"></a>00050 <span class="comment">/// always assumes that the struct tm is in UTC, and converts it</span>
<a name="l00051"></a>00051 <span class="comment">/// to time_t regardless of what TZ is currently set.</span>
<a name="l00052"></a>00052 <span class="comment">///</span>
<a name="l00053"></a>00053 <span class="comment">/// The difference between utc_mktime() and TzWrapper::iso_mktime()</span>
<a name="l00054"></a>00054 <span class="comment">/// is that iso_mktime() will parse straight from an ISO string,</span>
<a name="l00055"></a>00055 <span class="comment">/// and if the ISO timestamp ends in a 'Z', it will behave like</span>
<a name="l00056"></a>00056 <span class="comment">/// utc_mktime() except it will alter the TZ environment variable</span>
<a name="l00057"></a>00057 <span class="comment">/// to do it. If the ISO timestamp has no 'Z', then iso_mktime()</span>
<a name="l00058"></a>00058 <span class="comment">/// behaves like mktime().</span>
<a name="l00059"></a>00059 <span class="comment">///</span>
<a name="l00060"></a>00060 <span class="comment"></span>BXEXPORT time_t utc_mktime(<span class="keyword">struct</span> tm *utctime);
<a name="l00061"></a>00061
<a name="l00062"></a>00062 <span class="comment">//</span>
<a name="l00063"></a>00063 <span class="comment">// class TzWrapper</span>
<a name="l00064"></a>00064 <span class="comment">//</span><span class="comment"></span>
<a name="l00065"></a>00065 <span class="comment">/// Wrapper class for the TZ environment variable. This class allows</span>
<a name="l00066"></a>00066 <span class="comment">/// setting TZ to any number of variables, and will restore the original</span>
<a name="l00067"></a>00067 <span class="comment">/// setting on destruction.</span>
<a name="l00068"></a>00068 <span class="comment">///</span>
<a name="l00069"></a>00069 <span class="comment">/// By default, TzWrapper does not change the environment at all, but</span>
<a name="l00070"></a>00070 <span class="comment">/// only saves it. Alternately, you can use the timezone constructor</span>
<a name="l00071"></a>00071 <span class="comment">/// to save and set a new timezone on the fly.</span>
<a name="l00072"></a>00072 <span class="comment">///</span>
<a name="l00073"></a>00073 <span class="comment">/// Each Set() and Unset() function returns a reference to TzWrapper,</span>
<a name="l00074"></a>00074 <span class="comment">/// so that you can chain function calls like this:</span>
<a name="l00075"></a>00075 <span class="comment">///</span>
<a name="l00076"></a>00076 <span class="comment">/// time_t utc = TzWrapper("Canada/Pacific").mktime(&pacific_tm);</span>
<a name="l00077"></a>00077 <span class="comment">///</span>
<a name="l00078"></a>00078 <span class="comment">/// In addition, there are two static utility functions used to</span>
<a name="l00079"></a>00079 <span class="comment">/// convert ISO timestamps to struct tm* and time_t values.</span>
<a name="l00080"></a>00080 <span class="comment">///</span>
<a name="l00081"></a>00081 <span class="comment">/// Note: This class is not thread-safe, since it modifies the TZ</span>
<a name="l00082"></a>00082 <span class="comment">/// environment variable without locking. If other threads</span>
<a name="l00083"></a>00083 <span class="comment">/// use time functions, this may interfere with their behaviour.</span>
<a name="l00084"></a>00084 <span class="comment">///</span>
<a name="l00085"></a><a class="code" href="classBarry_1_1Sync_1_1TzWrapper.html">00085</a> <span class="comment"></span><span class="keyword">class </span>BXEXPORT <a class="code" href="classBarry_1_1Sync_1_1TzWrapper.html" title="Wrapper class for the TZ environment variable.">TzWrapper</a>
<a name="l00086"></a>00086 {
<a name="l00087"></a>00087 std::string m_orig_tz;
<a name="l00088"></a>00088 <span class="keywordtype">bool</span> m_tz_exists;
<a name="l00089"></a>00089 <span class="keywordtype">bool</span> m_dirty;
<a name="l00090"></a>00090
<a name="l00091"></a>00091 <span class="keyword">protected</span>:
<a name="l00092"></a>00092 <span class="keywordtype">void</span> SaveTz()
<a name="l00093"></a>00093 {
<a name="l00094"></a>00094 <span class="keywordtype">char</span> *ptz = getenv(<span class="stringliteral">"TZ"</span>);
<a name="l00095"></a>00095 <span class="keywordflow">if</span>( ptz )
<a name="l00096"></a>00096 m_orig_tz = ptz;
<a name="l00097"></a>00097 m_tz_exists = ptz;
<a name="l00098"></a>00098 }
<a name="l00099"></a>00099
<a name="l00100"></a>00100 <span class="keywordtype">void</span> RestoreTz()
<a name="l00101"></a>00101 {
<a name="l00102"></a>00102 <span class="keywordflow">if</span>( m_dirty ) {
<a name="l00103"></a>00103 <span class="keywordflow">if</span>( m_tz_exists )
<a name="l00104"></a>00104 Set(m_orig_tz.c_str());
<a name="l00105"></a>00105 <span class="keywordflow">else</span>
<a name="l00106"></a>00106 Unset();
<a name="l00107"></a>00107
<a name="l00108"></a>00108 m_dirty = <span class="keyword">false</span>;
<a name="l00109"></a>00109 }
<a name="l00110"></a>00110 }
<a name="l00111"></a>00111
<a name="l00112"></a>00112 <span class="keyword">public</span>:<span class="comment"></span>
<a name="l00113"></a>00113 <span class="comment"> /// Does not change TZ, only saves current setting</span>
<a name="l00114"></a><a class="code" href="classBarry_1_1Sync_1_1TzWrapper.html#ae2873ae6adbe53fd7e61109a4b39b554">00114</a> <span class="comment"></span> <a class="code" href="classBarry_1_1Sync_1_1TzWrapper.html" title="Wrapper class for the TZ environment variable.">TzWrapper</a>()
<a name="l00115"></a>00115 : m_dirty(false)
<a name="l00116"></a>00116 {
<a name="l00117"></a>00117 SaveTz();
<a name="l00118"></a>00118 }
<a name="l00119"></a>00119 <span class="comment"></span>
<a name="l00120"></a>00120 <span class="comment"> /// Saves current setting and sets TZ to new timezone value.</span>
<a name="l00121"></a>00121 <span class="comment"> /// If timezone is null, it is the same as calling Unset().</span>
<a name="l00122"></a><a class="code" href="classBarry_1_1Sync_1_1TzWrapper.html#a11b3c0192d3b4eb7471cce7159c3c6a2">00122</a> <span class="comment"></span> <span class="keyword">explicit</span> <a class="code" href="classBarry_1_1Sync_1_1TzWrapper.html" title="Wrapper class for the TZ environment variable.">TzWrapper</a>(<span class="keyword">const</span> <span class="keywordtype">char</span> *timezone)
<a name="l00123"></a>00123 : m_dirty(false)
<a name="l00124"></a>00124 {
<a name="l00125"></a>00125 SaveTz();
<a name="l00126"></a>00126 Set(timezone);
<a name="l00127"></a>00127 }
<a name="l00128"></a>00128
<a name="l00129"></a>00129 ~<a class="code" href="classBarry_1_1Sync_1_1TzWrapper.html" title="Wrapper class for the TZ environment variable.">TzWrapper</a>()
<a name="l00130"></a>00130 {
<a name="l00131"></a>00131 RestoreTz();
<a name="l00132"></a>00132 }
<a name="l00133"></a>00133 <span class="comment"></span>
<a name="l00134"></a>00134 <span class="comment"> /// Set TZ to a new value. If timezone is null, it is the</span>
<a name="l00135"></a>00135 <span class="comment"> /// same as calling Unset().</span>
<a name="l00136"></a>00136 <span class="comment"> ///</span>
<a name="l00137"></a>00137 <span class="comment"> /// If timezone is an empty or invalid timezone string, it</span>
<a name="l00138"></a>00138 <span class="comment"> /// is the same as calling SetUTC().</span>
<a name="l00139"></a><a class="code" href="classBarry_1_1Sync_1_1TzWrapper.html#a46e3e3ec5c35694810271476707a6186">00139</a> <span class="comment"></span> <a class="code" href="classBarry_1_1Sync_1_1TzWrapper.html" title="Wrapper class for the TZ environment variable.">TzWrapper</a>& Set(<span class="keyword">const</span> <span class="keywordtype">char</span> *timezone)
<a name="l00140"></a>00140 {
<a name="l00141"></a>00141 <span class="keywordflow">if</span>( timezone )
<a name="l00142"></a>00142 setenv(<span class="stringliteral">"TZ"</span>, timezone, 1);
<a name="l00143"></a>00143 <span class="keywordflow">else</span>
<a name="l00144"></a>00144 unsetenv(<span class="stringliteral">"TZ"</span>);
<a name="l00145"></a>00145 tzset();
<a name="l00146"></a>00146 m_dirty = <span class="keyword">true</span>;
<a name="l00147"></a>00147 <span class="keywordflow">return</span> *<span class="keyword">this</span>;
<a name="l00148"></a>00148 }
<a name="l00149"></a>00149 <span class="comment"></span>
<a name="l00150"></a>00150 <span class="comment"> /// Deletes TZ from the environment, which has the same effect</span>
<a name="l00151"></a>00151 <span class="comment"> /// as calling SetSysLocal(). This is not a permanent</span>
<a name="l00152"></a>00152 <span class="comment"> /// condition, since TZ will be restored to original state</span>
<a name="l00153"></a>00153 <span class="comment"> /// upon destruction.</span>
<a name="l00154"></a><a class="code" href="classBarry_1_1Sync_1_1TzWrapper.html#a27d8874df34bd4f04bd4430d0d4a2523">00154</a> <span class="comment"></span> <a class="code" href="classBarry_1_1Sync_1_1TzWrapper.html" title="Wrapper class for the TZ environment variable.">TzWrapper</a>& Unset()
<a name="l00155"></a>00155 {
<a name="l00156"></a>00156 unsetenv(<span class="stringliteral">"TZ"</span>);
<a name="l00157"></a>00157 tzset();
<a name="l00158"></a>00158 m_dirty = <span class="keyword">true</span>;
<a name="l00159"></a>00159 <span class="keywordflow">return</span> *<span class="keyword">this</span>;
<a name="l00160"></a>00160 }
<a name="l00161"></a>00161 <span class="comment"></span>
<a name="l00162"></a>00162 <span class="comment"> /// Set timezone to UTC</span>
<a name="l00163"></a><a class="code" href="classBarry_1_1Sync_1_1TzWrapper.html#aab3349c356c87e37d41841d78fd8f227">00163</a> <span class="comment"></span> <a class="code" href="classBarry_1_1Sync_1_1TzWrapper.html" title="Wrapper class for the TZ environment variable.">TzWrapper</a>& SetUTC()
<a name="l00164"></a>00164 {
<a name="l00165"></a>00165 <span class="keywordflow">return</span> Set(<span class="stringliteral">""</span>);
<a name="l00166"></a>00166 }
<a name="l00167"></a>00167 <span class="comment"></span>
<a name="l00168"></a>00168 <span class="comment"> /// Use system localtime. This overrides any TZ value that the</span>
<a name="l00169"></a>00169 <span class="comment"> /// user may have set before running your program.</span>
<a name="l00170"></a><a class="code" href="classBarry_1_1Sync_1_1TzWrapper.html#a64528d9b642db8defc4163c613ff0366">00170</a> <span class="comment"></span> <a class="code" href="classBarry_1_1Sync_1_1TzWrapper.html" title="Wrapper class for the TZ environment variable.">TzWrapper</a>& SetSysLocal()
<a name="l00171"></a>00171 {
<a name="l00172"></a>00172 <span class="keywordflow">return</span> Unset();
<a name="l00173"></a>00173 }
<a name="l00174"></a>00174 <span class="comment"></span>
<a name="l00175"></a>00175 <span class="comment"> /// Use the default TZ value that the user set before running</span>
<a name="l00176"></a>00176 <span class="comment"> /// this program. In most cases, this will be the user's</span>
<a name="l00177"></a>00177 <span class="comment"> /// preferred local timezone.</span>
<a name="l00178"></a><a class="code" href="classBarry_1_1Sync_1_1TzWrapper.html#af47fbd57f1417575a1c0c958d57ca395">00178</a> <span class="comment"></span> <a class="code" href="classBarry_1_1Sync_1_1TzWrapper.html" title="Wrapper class for the TZ environment variable.">TzWrapper</a>& SetDefault()
<a name="l00179"></a>00179 {
<a name="l00180"></a>00180 RestoreTz();
<a name="l00181"></a>00181 <span class="keywordflow">return</span> *<span class="keyword">this</span>;
<a name="l00182"></a>00182 }<span class="comment"></span>
<a name="l00183"></a>00183 <span class="comment"> /// Same as SetDefault()</span>
<a name="l00184"></a><a class="code" href="classBarry_1_1Sync_1_1TzWrapper.html#add71d2129221171a01fe5efc5e3aeeab">00184</a> <span class="comment"></span> <a class="code" href="classBarry_1_1Sync_1_1TzWrapper.html" title="Wrapper class for the TZ environment variable.">TzWrapper</a>& SetOrig()
<a name="l00185"></a>00185 {
<a name="l00186"></a>00186 <span class="keywordflow">return</span> SetDefault();
<a name="l00187"></a>00187 }
<a name="l00188"></a>00188
<a name="l00189"></a>00189 <span class="comment">//</span>
<a name="l00190"></a>00190 <span class="comment">// C library wrappers, for calls like:</span>
<a name="l00191"></a>00191 <span class="comment">// time_t t = TzWrapper("Canada/Pacific").mktime(tm);</span>
<a name="l00192"></a>00192 <span class="comment">//</span>
<a name="l00193"></a>00193 <span class="keywordtype">char</span>* asctime(<span class="keyword">const</span> <span class="keyword">struct</span> tm *t)<span class="keyword"> const </span>{ return ::asctime(t); }
<a name="l00194"></a>00194 <span class="keywordtype">char</span>* asctime_r(<span class="keyword">const</span> <span class="keyword">struct</span> tm *t, <span class="keywordtype">char</span> *buf)<span class="keyword"> const</span>
<a name="l00195"></a>00195 <span class="keyword"> </span>{ return ::asctime_r(t, buf); }
<a name="l00196"></a>00196 <span class="keywordtype">char</span>* ctime(<span class="keyword">const</span> time_t *t)<span class="keyword"> const </span>{ return ::ctime(t); }
<a name="l00197"></a>00197 <span class="keywordtype">char</span>* ctime_r(<span class="keyword">const</span> time_t *t, <span class="keywordtype">char</span> *buf)<span class="keyword"> const</span>
<a name="l00198"></a>00198 <span class="keyword"> </span>{ return ::ctime_r(t, buf); }
<a name="l00199"></a>00199 <span class="keyword">struct </span>tm* gmtime(<span class="keyword">const</span> time_t *t)<span class="keyword"> const </span>{ return ::gmtime(t); }
<a name="l00200"></a>00200 <span class="keyword">struct </span>tm* gmtime_r(<span class="keyword">const</span> time_t *t, <span class="keyword">struct</span> tm *result)<span class="keyword"> const</span>
<a name="l00201"></a>00201 <span class="keyword"> </span>{ return ::gmtime_r(t, result); }
<a name="l00202"></a>00202 <span class="keyword">struct </span>tm* localtime(<span class="keyword">const</span> time_t *t)<span class="keyword"> const </span>{ return ::localtime(t); }
<a name="l00203"></a>00203 <span class="keyword">struct </span>tm* localtime_r(<span class="keyword">const</span> time_t *t, <span class="keyword">struct</span> tm *result)<span class="keyword"> const</span>
<a name="l00204"></a>00204 <span class="keyword"> </span>{ return ::localtime_r(t, result); }
<a name="l00205"></a>00205 time_t mktime(<span class="keyword">struct</span> tm *t) { return ::mktime(t); }
<a name="l00206"></a>00206
<a name="l00207"></a>00207 <span class="comment">//</span>
<a name="l00208"></a>00208 <span class="comment">// Additional utility functions</span>
<a name="l00209"></a>00209 <span class="comment">//</span>
<a name="l00210"></a>00210 <span class="comment"></span>
<a name="l00211"></a>00211 <span class="comment"> /// Converts an ISO timestamp (YYYYMMDDTHHMMWW[Z]) into a</span>
<a name="l00212"></a>00212 <span class="comment"> /// unix time_t. If the 'Z' UTC flag is not specified, then</span>
<a name="l00213"></a>00213 <span class="comment"> /// the timestamp will be assumed to be in the current</span>
<a name="l00214"></a>00214 <span class="comment"> /// default timezone. Otherwise, SetUTC() will be used for the</span>
<a name="l00215"></a>00215 <span class="comment"> /// conversion.</span>
<a name="l00216"></a>00216 <span class="comment"> ///</span>
<a name="l00217"></a>00217 <span class="comment"> /// This function uses an internal TzWrapper to adjust TZ</span>
<a name="l00218"></a>00218 <span class="comment"> /// if necessary, which is why it is a static function</span>
<a name="l00219"></a>00219 <span class="comment"> /// of TzWrapper, instead of a standalone function.</span>
<a name="l00220"></a>00220 <span class="comment"> ///</span>
<a name="l00221"></a>00221 <span class="comment"></span> <span class="keyword">static</span> time_t iso_mktime(<span class="keyword">const</span> <span class="keywordtype">char</span> *timestamp);
<a name="l00222"></a>00222 };
<a name="l00223"></a>00223
<a name="l00224"></a>00224 }} <span class="comment">// namespace Barry::Sync</span>
<a name="l00225"></a>00225
<a name="l00226"></a>00226 <span class="preprocessor">#endif</span>
<a name="l00227"></a>00227 <span class="preprocessor"></span>
</pre></div></div>
<hr class="footer"/><address style="text-align: right;"><small>Generated by
<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.6.2-20100208 </small></address>
</body>
</html>
