doc/html/date_time/local_time.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
   2 <html>
   3 <head>
   4 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
   5 <title>Local Time</title>
   6 <link rel="stylesheet" href="../../../doc/src/boostbook.css" type="text/css">
   7 <meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
   8 <link rel="home" href="../index.html" title="The Boost C++ Libraries BoostBook Documentation Subset">
   9 <link rel="up" href="../date_time.html" title="Chapter&#160;12.&#160;Boost.Date_Time">
  10 <link rel="prev" href="posix_time.html" title="Posix Time">
  11 <link rel="next" href="date_time_io.html" title="Date Time Input/Output">
  12 </head>
  13 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
  14 <table cellpadding="2" width="100%"><tr>
  15 <td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../boost.png"></td>
  16 <td align="center"><a href="../../../index.html">Home</a></td>
  17 <td align="center"><a href="../../../libs/libraries.htm">Libraries</a></td>
  18 <td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
  19 <td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
  20 <td align="center"><a href="../../../more/index.htm">More</a></td>
  21 </tr></table>
  22 <hr>
  23 <div class="spirit-nav">
  24 <a accesskey="p" href="posix_time.html"><img src="../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../date_time.html"><img src="../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="date_time_io.html"><img src="../../../doc/src/images/next.png" alt="Next"></a>
  25 </div>
  26 <div class="section">
  27 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
  28 <a name="date_time.local_time"></a>Local Time</h2></div></div></div>
  29 <div class="toc"><dl class="toc">
  30 <dt><span class="section"><a href="local_time.html#date_time.local_time.time_zone_base">Time Zone (abstract)</a></span></dt>
  31 <dt><span class="section"><a href="local_time.html#date_time.local_time.posix_time_zone">Posix Time Zone</a></span></dt>
  32 <dt><span class="section"><a href="local_time.html#date_time.local_time.tz_database">Time Zone Database</a></span></dt>
  33 <dt><span class="section"><a href="local_time.html#date_time.local_time.custom_time_zone">Custom Time Zone</a></span></dt>
  34 <dt><span class="section"><a href="local_time.html#date_time.local_time.local_date_time">Local Date Time</a></span></dt>
  35 <dt><span class="section"><a href="local_time.html#date_time.local_time.local_time_period">Local Time Period</a></span></dt>
  36 </dl></div>
  37 <h3>
  38 <a name="idp212078816"></a>Local Time System</h3>
  39 <p>
  40     <a class="link" href="local_time.html#local_intro">Introduction</a> --
  41     <a class="link" href="local_time.html#local_ex">Usage Examples</a>
  42   </p>
  43 <a name="local_intro"></a><h4>
  44 <a name="idp212082480"></a>Introduction</h4>
  45 <p>
  46     The library supports 4 main extensions for the management of local times. This includes
  47     </p>
  48 <table border="0" summary="Simple list" class="simplelist">
  49 <tr><td>local_date_time -- locally adjusted time point</td></tr>
  50 <tr><td>posix_time_zone -- time zone defined by posix string (eg: "EST10EDT,M10.5.0,M3.5.0/03")</td></tr>
  51 <tr><td>time_zone_database -- get time zones by region from .csv file (eg: America/New York)</td></tr>
  52 <tr><td>time_zone -- abstract time zone interface</td></tr>
  53 </table>
  54 <p>
  55   </p>
  56 <p>
  57     Together, these extensions define a time system adjusted for recording times related to a specific earth location. This time system utilizes all the features and benefits of the posix_time system (see <a class="link" href="posix_time.html" title="Posix Time">posix_time</a> for full details). It uses a time_zone object which contains all the necessary data/rules to enable adjustments to and from various time zones. The time_zone objects used in date_time are handled via a boost::shared_ptr&lt;boost::local_time::time_zone&gt;.
  58   </p>
  59 <p>
  60     The phrase "wall-clock" refers to the time that would be shown on a wall clock in a particular time zone at any point in time. Local_time uses a time zone object to account for differences in time zones and daylight savings adjustments. For example: While 5:00 pm, October 10, 2004 in Sydney Australia occurs at exactly the same instant as 3:00 am, October 10, 2004 in New York USA, it is a 14 hour difference in wall-clock times. However, a point in time just one day later will result in a 16 hour difference in wall-clock time due to daylight savings adjustments in both time zones. The local_time system tracks these by means of a time point, stored as UTC, and time_zone objects that contain all the necessary data to correctly calculate wall-clock times.
  61   </p>
  62 <a name="local_ex"></a><h4>
  63 <a name="idp212089904"></a>Usage Examples</h4>
  64 <p>
  65     </p>
  66 <div class="informaltable"><table class="table">
  67 <colgroup>
  68 <col>
  69 <col>
  70 </colgroup>
  71 <thead><tr>
  72 <th>Example</th>
  73 <th>Description</th>
  74 </tr></thead>
  75 <tbody>
  76 <tr>
  77 <td><a class="link" href="examples.html#date_time.examples.simple_time_zone" title="Simple Time Zones">Simple Time Zone</a></td>
  78 <td>Side by side examples of Time Zone usage. Both <span class="type">custom_time_zone</span> and <span class="type">posix_time_zone</span> are shown.</td>
  79 </tr>
  80 <tr>
  81 <td><a class="link" href="examples.html#date_time.examples.calc_rules" title="Daylight Savings Calc Rules">Daylight Savings Calc Rules</a></td>
  82 <td>Simple example showing the creation of all five <span class="type">dst_calc_rule</span> types.</td>
  83 </tr>
  84 <tr>
  85 <td><a class="link" href="examples.html#date_time.examples.seconds_since_epoch" title="Seconds Since Epoch">Seconds Since Epoch</a></td>
  86 <td>Example that calculates the total seconds elapsed since the epoch (1970-Jan-01) utilizing local_date_time.</td>
  87 </tr>
  88 </tbody>
  89 </table></div>
  90 <p>
  91   </p>
  92 <div class="section">
  93 <div class="titlepage"><div><div><h3 class="title">
  94 <a name="date_time.local_time.time_zone_base"></a>Time Zone (abstract)</h3></div></div></div>
  95 <a class="link" href="local_time.html#time_zone_base_intro">Introduction</a> --
  96   <a class="link" href="local_time.html#time_zone_base_header">Header</a> --
  97   <a class="link" href="local_time.html#time_zone_base_constr">Construction</a> --
  98   <a class="link" href="local_time.html#time_zone_base_accessors">Accessors</a><a name="time_zone_base_intro"></a><h4>
  99 <a name="idp212107488"></a>Introduction</h4>
 100 <p>
 101     The time_zone_base class is an abstract base class template for representing time zones. Time zones are a set of data and rules that provide information about a time zone. The date_time library handles time_zones by means of a boost::shared_ptr&lt;time_zone_base&gt;. A user's custom time zone class will work in the date_time library by means of this shared_ptr.
 102   </p>
 103 <p>
 104     For convienience, the time_zone_base class is typedef'd as time_zone. All references in the documentation to time_zone, are referring to this typedef.
 105   </p>
 106 <a name="time_zone_base_header"></a><h4>
 107 <a name="idp212110320"></a>Header</h4>
 108 <p>
 109     The time_zone_base class is defined in the header:
 110     </p>
 111 <pre class="programlisting">#include "boost/date_time/time_zone_base.hpp"
 112     </pre>
 113 <p>
 114   </p>
 115 <a name="time_zone_base_constr"></a><h4>
 116 <a name="idp212112880"></a>Construction</h4>
 117 <p>
 118     A default constructor is provided in the time_zone_base class. There are no private data members in this base class to initialize.
 119   </p>
 120 <p>
 121     Template parameters are time_type (typically posix_time::ptime) and CharT (defaults to char).
 122   </p>
 123 <a name="time_zone_base_accessors"></a><h4>
 124 <a name="idp212115296"></a>Accessors</h4>
 125 <p>
 126     All of the accessors listed here are pure virtual functions.
 127   </p>
 128 <p>
 129     </p>
 130 <div class="informaltable"><table class="table">
 131 <colgroup>
 132 <col>
 133 <col>
 134 </colgroup>
 135 <thead><tr>
 136 <th>Syntax</th>
 137 <th>Description</th>
 138 </tr></thead>
 139 <tbody>
 140 <tr>
 141 <td valign="top"><pre class="screen">
 142 string_type dst_zone_abbrev();</pre></td>
 143 <td>Returns the daylight savings abbreviation for the represented time zone.</td>
 144 </tr>
 145 <tr>
 146 <td valign="top"><pre class="screen">
 147 string_type std_zone_abbrev();</pre></td>
 148 <td>Returns the standard abbreviation for the represented time zone.</td>
 149 </tr>
 150 <tr>
 151 <td valign="top"><pre class="screen">
 152 string_type dst_zone_name();</pre></td>
 153 <td>Returns the daylight savings name for the represented time zone.</td>
 154 </tr>
 155 <tr>
 156 <td valign="top"><pre class="screen">
 157 string_type std_zone_name();</pre></td>
 158 <td>Returns the standard name for the represented time zone.</td>
 159 </tr>
 160 <tr>
 161 <td valign="top"><pre class="screen">bool has_dst();</pre></td>
 162 <td>Returns true if this time zone does not make a daylight savings shift.</td>
 163 </tr>
 164 <tr>
 165 <td valign="top"><pre class="screen">
 166 time_type dst_local_start_time(year_type);</pre></td>
 167 <td>The date and time daylight savings time begins in given year.</td>
 168 </tr>
 169 <tr>
 170 <td valign="top"><pre class="screen">
 171 time_type dst_local_end_time(year_type);</pre></td>
 172 <td valign="top">The date and time daylight savings time ends in given year.</td>
 173 </tr>
 174 <tr>
 175 <td valign="top"><pre class="screen">
 176 time_duration_type base_utc_offset();</pre></td>
 177 <td>The amount of time offset from UTC (typically in hours).</td>
 178 </tr>
 179 <tr>
 180 <td valign="top"><pre class="screen">
 181 time_duration_type dst_offset();</pre></td>
 182 <td>The amount of time shifted during daylight savings.</td>
 183 </tr>
 184 <tr>
 185 <td valign="top"><pre class="screen">
 186 std::string to_posix_string();</pre></td>
 187 <td>Returns a posix time zone string representation of this time_zone_base object. For a detailed description of a posix time zone string see <a class="link" href="local_time.html#date_time.local_time.posix_time_zone" title="Posix Time Zone">posix_time_zone</a>.</td>
 188 </tr>
 189 </tbody>
 190 </table></div>
 191 <p>
 192   </p>
 193 </div>
 194 <div class="section">
 195 <div class="titlepage"><div><div><h3 class="title">
 196 <a name="date_time.local_time.posix_time_zone"></a>Posix Time Zone</h3></div></div></div>
 197 <a class="link" href="local_time.html#posix_time_zone_intro">Introduction</a> --
 198   <a class="link" href="local_time.html#posix_time_zone_notes">Important Notes</a> --
 199   <a class="link" href="local_time.html#posix_time_zone_header">Header</a> --
 200   <a class="link" href="local_time.html#posix_time_zone_constr">Construction</a> --
 201   <a class="link" href="local_time.html#posix_time_zone_accessors">Accessors</a><a name="posix_time_zone_intro"></a><h4>
 202 <a name="idp212147632"></a>Introduction</h4>
 203 <p>
 204     A posix_time_zone object is a set of data and rules that provide information about a time zone. Information such as the offset from UTC, it's name and abbreviation, as well as daylight savings rules, called <a class="link" href="local_time.html#date_time.local_time.dst_calc_rules">dst_calc_rules</a>. These rules are stored as a boost::shared_ptr&lt;dst_calc_rules&gt;.
 205   </p>
 206 <p>
 207     As a convenience, a typedef for shared_ptr&lt;dst_calc_rules&gt; is provided.
 208     </p>
 209 <pre class="programlisting">typedef boost::shared_ptr&lt;dst_calc_rules&gt; local_time::dst_calc_rule_ptr;</pre>
 210 <p>
 211   </p>
 212 <p>
 213     A posix_time_zone is unique in that the object is created from a Posix time zone string (IEEE Std 1003.1). A POSIX time zone string takes the form of:
 214     </p>
 215 <div class="literallayout"><p><br>
 216 &#160;&#160;&#160;&#160;&#160;&#160;"std&#160;offset&#160;dst&#160;[offset],start[/time],end[/time]"&#160;(w/no&#160;spaces).</p></div>
 217 <p>'std' specifies the abbrev of the time zone. 'offset' is the offset from UTC. 'dst' specifies the abbrev of the time zone during daylight savings time. The second offset is how many hours changed during DST. 'start' and 'end' are the dates when DST goes into (and out of) effect. 'offset' takes the form of:
 218     </p>
 219 <div class="literallayout"><p><br>
 220 &#160;&#160;&#160;&#160;&#160;&#160;[+|-]hh[:mm[:ss]]&#160;{h=0-23,&#160;m/s=0-59}</p></div>
 221 <p>'time' and 'offset' take the same form. 'start' and 'end' can be one of three forms:
 222     </p>
 223 <div class="literallayout"><p><br>
 224 &#160;&#160;&#160;&#160;&#160;&#160;Mm.w.d&#160;{month=1-12,&#160;week=1-5&#160;(5&#160;is&#160;always&#160;last),&#160;day=0-6}<br>
 225 &#160;&#160;&#160;&#160;&#160;&#160;Jn&#160;{n=1-365&#160;Feb29&#160;is&#160;never&#160;counted}<br>
 226 &#160;&#160;&#160;&#160;&#160;&#160;n&#160;{n=0-365&#160;Feb29&#160;is&#160;counted&#160;in&#160;leap&#160;years}</p></div>
 227 <p>
 228   </p>
 229 <p>
 230     Exceptions will be thrown under the following conditions:
 231     </p>
 232 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
 233 <li class="listitem">An exception will be thrown for an invalid date spec (see <a class="link" href="gregorian.html#date_time.gregorian.date_class" title="Date">date class</a>).</li>
 234 <li class="listitem">A boost::local_time::bad_offset exception will be thrown for:</li>
 235 <li class="listitem">A DST start or end offset that is negative or more than 24 hours.</li>
 236 <li class="listitem">A UTC zone that is greater than +14 or less than -12 hours.</li>
 237 <li class="listitem">A boost::local_time::bad_adjustment exception will be thrown for a DST adjustment that is 24 hours or more (positive or negative)</li>
 238 </ul></div>
 239 <p>
 240   </p>
 241 <p>As stated above, the 'offset' and '/time' portions of the string are not required. If they are not given they default to 01:00 for 'offset', and 02:00 for both occurrences of '/time'.
 242   </p>
 243 <p>
 244     Some examples are:
 245     </p>
 246 <div class="literallayout"><p><br>
 247 &#160;&#160;&#160;&#160;&#160;&#160;"PST-8PDT01:00:00,M4.1.0/02:00:00,M10.1.0/02:00:00"<br>
 248 &#160;&#160;&#160;&#160;&#160;&#160;"PST-8PDT,M4.1.0,M10.1.0"</p></div>
 249 <p>These two are actually the same specification (defaults were used in the second string). This zone lies eight hours west of GMT and makes a one hour shift forward during daylight savings time. Daylight savings for this zone starts on the first Sunday of April at 2am, and ends on the first Sunday of October at 2am.
 250     </p>
 251 <div class="literallayout"><p><br>
 252 &#160;&#160;&#160;&#160;&#160;&#160;"MST-7"</p></div>
 253 <p>This zone is as simple as it gets. This zone lies seven hours west of GMT and has no daylight savings.
 254     </p>
 255 <div class="literallayout"><p><br>
 256 &#160;&#160;&#160;&#160;&#160;&#160;"EST10EDT,M10.5.0,M3.5.0/03"</p></div>
 257 <p>This string describes the time zone for Sydney Australia. It lies ten hours east of GMT and makes a one hour shift forward during daylight savings. Being located in the southern hemisphere, daylight savings begins on the last Sunday in October at 2am and ends on the last Sunday in March at 3am.
 258     </p>
 259 <div class="literallayout"><p><br>
 260 &#160;&#160;&#160;&#160;&#160;&#160;"FST+3FDT02:00,J60/00,J304/02"</p></div>
 261 <p>This specification describes a fictitious zone that lies three hours east of GMT. It makes a two hour shift forward for daylight savings which begins on March 1st at midnight, and ends on October 31st at 2am. The 'J' designation in the start/end specs signifies that counting starts at one and February 29th is never counted.
 262     </p>
 263 <div class="literallayout"><p><br>
 264 &#160;&#160;&#160;&#160;&#160;&#160;"FST+3FDT,59,304"</p></div>
 265 <p>This specification is significant because of the '59'. The lack of 'J' for the start and end dates, indicates that the Julian day-count begins at zero and ends at 365. If you do the math, you'll see that allows for a total of 366 days. This is fine in leap years, but in non-leap years '59' (Feb-29) does not exist. This will construct a valid posix_time_zone object but an exception will be thrown if the date of '59' is accessed in a non-leap year. Ex:
 266     </p>
 267 <pre class="programlisting">posix_time_zone leap_day(std::string("FST+3FDT,59,304"));
 268 leap_day.dst_local_start_time(2004); // ok
 269 leap_day.dst_local_start_time(2003); // Exception thrown</pre>
 270 <p>
 271   </p>
 272 <p>
 273     The posix_time_zone objects are used via a boost::shared_ptr&lt;local_time::time_zone_base&gt;. As a convenience, a typedef for boost::shared_ptr&lt;local_time::time_zone_base&gt; is provided:
 274     </p>
 275 <pre class="programlisting">typedef boost::shared_ptr&lt;time_zone_base&gt; local_time::time_zone_ptr;</pre>
 276 <p>
 277   </p>
 278 <p>
 279     See <a class="link" href="examples.html#date_time.examples.simple_time_zone" title="Simple Time Zones">Simple time zone</a> for a side by side example of time_zone and posix_time_zone usage.
 280   </p>
 281 <a name="posix_time_zone_notes"></a><h4>
 282 <a name="idp212171584"></a>Important Notes</h4>
 283 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
 284 <li class="listitem">posix_time_zone objects use the standard and daylight savings abbreviations in place of the full names (see <a class="link" href="local_time.html#posix_time_zone_accessors">Accessors</a> below).</li>
 285 <li class="listitem">'Jn' and 'n' date specifications can not be mixed in a specification string. Ex: "FST+3FDT,59,J304" </li>
 286 <li class="listitem">'n' date specification of 59 represents Feb-29. Do not attempt to access in a non-leap year or an exception will be thrown.</li>
 287 </ul></div>
 288 <a name="posix_time_zone_header"></a><h4>
 289 <a name="idp212175744"></a>Header</h4>
 290 <p>
 291     The inclusion of a single header will bring in all boost::local_time types, functions, and IO operators.
 292     </p>
 293 <pre class="programlisting">#include "boost/date_time/local_time/local_time.hpp"</pre>
 294 <p>
 295   </p>
 296 <a name="posix_time_zone_constr"></a><h4>
 297 <a name="idp212178288"></a>Construction</h4>
 298 <p>
 299     </p>
 300 <div class="informaltable"><table class="table">
 301 <colgroup>
 302 <col>
 303 <col>
 304 </colgroup>
 305 <thead><tr>
 306 <th>Syntax</th>
 307 <th>Example</th>
 308 </tr></thead>
 309 <tbody><tr>
 310 <td valign="top"><pre class="screen">posix_time_zone(std::string)</pre></td>
 311 <td>
 312 <pre class="screen">std::string nyc("EST-5EDT,M4.1.0,M10.5.0");
 313 time_zone_ptr zone(new posix_time_zone(nyc));</pre>
 314             </td>
 315 </tr></tbody>
 316 </table></div>
 317 <p>
 318   </p>
 319 <a name="posix_time_zone_accessors"></a><h4>
 320 <a name="idp212185760"></a>Accessors</h4>
 321 <p>
 322     </p>
 323 <div class="informaltable"><table class="table">
 324 <colgroup>
 325 <col>
 326 <col>
 327 </colgroup>
 328 <thead>
 329 <tr>
 330 <th rowspan="2" valign="top">Syntax</th>
 331 <th>Description</th>
 332 </tr>
 333 <tr><th>Example</th></tr>
 334 </thead>
 335 <tbody>
 336 <tr>
 337 <td rowspan="2" valign="top"><pre class="screen">std::string dst_zone_abbrev()</pre></td>
 338 <td>Returns the daylight savings abbreviation for the represented time zone.</td>
 339 </tr>
 340 <tr><td><pre class="screen">nyc_zone_sh_ptr-&gt;dst_zone_abbrev(); // "EDT"</pre></td></tr>
 341 <tr>
 342 <td rowspan="2" valign="top"><pre class="screen">std::string std_zone_abbrev()</pre></td>
 343 <td>Returns the standard abbreviation for the represented time zone.</td>
 344 </tr>
 345 <tr><td><pre class="screen">nyc_zone_sh_ptr-&gt;std_zone_abbrev(); // "EST"</pre></td></tr>
 346 <tr>
 347 <td rowspan="2" valign="top"><pre class="screen">std::string dst_zone_name()</pre></td>
 348 <td>Returns the daylight savings ABBREVIATION for the represented time zone.</td>
 349 </tr>
 350 <tr><td><pre class="screen">nyc_zone_sh_ptr-&gt;dst_zone_name(); // "EDT"</pre></td></tr>
 351 <tr>
 352 <td rowspan="2" valign="top"><pre class="screen">std::string std_zone_name()</pre></td>
 353 <td>Returns the standard ABBREVIATION for the represented time zone.</td>
 354 </tr>
 355 <tr><td><pre class="screen">nyc_zone_sh_ptr-&gt;std_zone_name(); // "EST"</pre></td></tr>
 356 <tr>
 357 <td rowspan="2" valign="top"><pre class="screen">bool has_dst()</pre></td>
 358 <td>Returns true when time_zone's shared_ptr to dst_calc_rules is not NULL.</td>
 359 </tr>
 360 <tr><td>
 361 <pre class="screen">nyc_zone_sh_ptr-&gt;has_dst(); // true
 362 phx_zone_sh_ptr-&gt;has_dst(); // false</pre>
 363             </td></tr>
 364 <tr>
 365 <td rowspan="2" valign="top"><pre class="screen">
 366 ptime dst_local_start_time(greg_year)</pre></td>
 367 <td>The date and time daylight savings time begins in given year. Returns not_a_date_time if this zone has no daylight savings.</td>
 368 </tr>
 369 <tr><td><pre class="screen">nyc_zone_sh_ptr-&gt;dst_local_start_time(2004);
 370 // 2004-Apr-04 02:00</pre></td></tr>
 371 <tr>
 372 <td rowspan="2" valign="top"><pre class="screen">
 373 ptime dst_local_end_time(greg_year)</pre></td>
 374 <td>The date and time daylight savings time ends in given year. Returns not_a_date_time if this zone has no daylight savings.</td>
 375 </tr>
 376 <tr><td><pre class="screen">nyc_zone_sh_ptr-&gt;dst_local_end_time(2004);
 377 // 2004-Oct-31 02:00</pre></td></tr>
 378 <tr>
 379 <td rowspan="2" valign="top"><pre class="screen">
 380 time_duration base_utc_offset()</pre></td>
 381 <td>The amount of time offset from UTC (typically in hours).</td>
 382 </tr>
 383 <tr><td><pre class="screen">nyc_zone_sh_ptr-&gt;base_utc_offset(); // -05:00</pre></td></tr>
 384 <tr>
 385 <td rowspan="2" valign="top"><pre class="screen">posix_time::time_duration dst_offset()</pre></td>
 386 <td>The amount of time shifted during daylight savings.</td>
 387 </tr>
 388 <tr><td><pre class="screen">nyc_zone_sh_ptr-&gt;dst_offset(); // 01:00</pre></td></tr>
 389 <tr>
 390 <td rowspan="2" valign="top"><pre class="screen">std::string to_posix_string()</pre></td>
 391 <td>Returns a posix time zone string representation of this time_zone_base object. Depending on how the time_zone object was created, the date-spec format of the string will be in either 'M' notation or 'n' notation. Every possible date-spec that can be represented in 'J' notation can also be represented in 'n' notation. The reverse is not true so only 'n' notation is used for these types of date-specs. For a detailed description of a posix time zone string see <a class="link" href="local_time.html#date_time.local_time.posix_time_zone" title="Posix Time Zone">posix_time_zone</a>.</td>
 392 </tr>
 393 <tr><td><pre class="screen">nyc_zone_sh_ptr-&gt;to_posix_string();
 394 // "EST-05EDT+01,M4.1.0/02:00,M10.5.0/02:00"
 395 phx_zone_sh_ptr-&gt;to_posix_string();
 396 // "MST-07"
 397             </pre></td></tr>
 398 </tbody>
 399 </table></div>
 400 <p>
 401   </p>
 402 </div>
 403 <div class="section">
 404 <div class="titlepage"><div><div><h3 class="title">
 405 <a name="date_time.local_time.tz_database"></a>Time Zone Database</h3></div></div></div>
 406 <a class="link" href="local_time.html#tz_database_intro">Introduction</a> --
 407   <a class="link" href="local_time.html#tz_database_header">Header</a> --
 408   <a class="link" href="local_time.html#tz_database_constr">Construction</a> --
 409   <a class="link" href="local_time.html#tz_database_accessors">Accessors</a> --
 410   <a class="link" href="local_time.html#tz_database_datafile">Data File Details</a><a name="tz_database_intro"></a><h4>
 411 <a name="idp212234704"></a>Introduction</h4>
 412 <p>
 413     The local_time system depends on the ability to store time zone information. Our Time Zone Database (tz_database) is a means of permanently storing that data. The specifications for many time zones (377 at this time) are provided. These specifications are based on data found in the <a href="http://www.twinsun.com/tz/tz-link.htm" target="_top">zoneinfo datebase</a>. The specifications are stored in the file:</p>
 414 <pre class="screen">libs/date_time/data/date_time_zonespec.csv</pre>
 415 <p>. While this file already contains specifications for many time zones, it's real intent is for the user to modify it by adding (or removing) time zones to fit their application. See <a class="link" href="local_time.html#tz_database_datafile">Data File Details</a> to learn how this is accomplished.
 416   </p>
 417 <a name="tz_database_header"></a><h4>
 418 <a name="idp212239296"></a>Header</h4>
 419 <p>
 420     The inclusion of a single header will bring in all boost::local_time types, functions, and IO operators.
 421     </p>
 422 <pre class="programlisting">#include "boost/date_time/local_time/local_time.hpp"
 423     </pre>
 424 <p>
 425   </p>
 426 <a name="tz_database_constr"></a><h4>
 427 <a name="idp212241920"></a>Construction</h4>
 428 <p>
 429     The only constructor takes no arguments and creates an empty database. It is up to the user to populate the database. This is typically achieved by loading the desired datafile, but can also be accomplished by means of the <code class="computeroutput">add_record(...)</code> function (see the <a class="link" href="local_time.html#tz_database_accessors">Accessors table</a>). A <code class="computeroutput">local_time::data_not_accessible</code> exception will be thrown if given zonespec file cannot be found. <code class="computeroutput">local_time::bad_field_count</code> exception will be thrown if the number of fields in given zonespec file is incorrect.
 430   </p>
 431 <p>
 432     </p>
 433 <div class="informaltable"><table class="table">
 434 <colgroup>
 435 <col>
 436 <col>
 437 </colgroup>
 438 <thead><tr>
 439 <th rowspan="2" valign="top">Syntax</th>
 440 <th>Description</th>
 441 </tr></thead>
 442 <tbody>
 443 <tr>
 444 <td rowspan="2" valign="top"><pre class="screen">tz_database()</pre></td>
 445 <td>Constructor creates an empty database.</td>
 446 </tr>
 447 <tr><td><pre class="screen">tz_database tz_db;</pre></td></tr>
 448 <tr>
 449 <td rowspan="2" valign="top"><pre class="screen">bool load_from_file(std::string)</pre></td>
 450 <td>Parameter is path to a time zone spec csv file (see <a class="link" href="local_time.html#tz_database_datafile">Data File Details</a> for details on the contents of this file). This function populates the database with time zone records found in the zone spec file. A <code class="computeroutput">local_time::data_not_accessible</code> exception will be thrown if given zonespec file cannot be found. <code class="computeroutput">local_time::bad_field_count</code> exception will be thrown if the number of fields in given zonespec file is incorrect.</td>
 451 </tr>
 452 <tr><td>
 453 <pre class="screen">tz_database tz_db;
 454 tz_db.load_from_file("./date_time_zonespec.csv");</pre>
 455             </td></tr>
 456 </tbody>
 457 </table></div>
 458 <p>
 459   </p>
 460 <a name="tz_database_accessors"></a><h4>
 461 <a name="idp212260528"></a>Accessors</h4>
 462 <p>
 463     </p>
 464 <div class="informaltable"><table class="table">
 465 <colgroup>
 466 <col>
 467 <col>
 468 </colgroup>
 469 <thead>
 470 <tr>
 471 <th rowspan="2" valign="top">Syntax</th>
 472 <th>Description</th>
 473 </tr>
 474 <tr><th>Example</th></tr>
 475 </thead>
 476 <tbody>
 477 <tr>
 478 <td rowspan="2" valign="top"><pre class="screen">bool tz_db.add_record(std::string id,
 479                       <a class="link" href="local_time.html#date_time.local_time.custom_time_zone_ptr">time_zone_ptr</a> tz);</pre></td>
 480 <td>Adds a time_zone, or a posix_time_zone, to the database. ID is the region name for this zone (Ex: "America/Phoenix").</td>
 481 </tr>
 482 <tr><td>
 483 <pre class="screen">time_zone_ptr zone(
 484   new posix_time_zone("PST-8PDT,M4.1.0,M10.1.0")
 485 );
 486 std::string id("America/West_Coast");
 487 tz_db.add_record(id, zone);</pre>
 488             </td></tr>
 489 <tr>
 490 <td rowspan="2" valign="top"><pre class="screen">time_zone_ptr
 491   tz_db.time_zone_from_region(string id);</pre></td>
 492 <td>Returns a time_zone, via a time_zone_ptr, that matches the region listed in the data file. A null pointer is returned if no match is found.
 493             </td>
 494 </tr>
 495 <tr><td>
 496 <pre class="screen">time_zone_ptr nyc =
 497   tz_db.time_zone_from_region("America/New_York");</pre>
 498             </td></tr>
 499 <tr>
 500 <td rowspan="2" valign="top"><pre class="screen">vector&lt;string&gt; tz_db.region_list();</pre></td>
 501 <td>Returns a vector of strings that holds all the region ID strings from the database.</td>
 502 </tr>
 503 <tr><td>
 504 <pre class="screen">std::vector&lt;std::string&gt; regions;
 505 regions = tz_db.region_list();</pre>
 506             </td></tr>
 507 </tbody>
 508 </table></div>
 509 <p>
 510   </p>
 511 <a name="tz_database_datafile"></a><h4>
 512 <a name="idp212278880"></a>Data File Details</h4>
 513 <a class="link" href="local_time.html#tz_database_fields">Field Description/Details</a><p>
 514     The csv file containing the zone_specs used by the boost::local_time::tz_database is intended to be customized by the library user. When customizing this file (or creating your own) the file must follow a specific format.
 515   </p>
 516 <p>
 517     This first line is expected to contain column headings and is therefore
 518 not processed by the tz_database.
 519   </p>
 520 <p>
 521     Each record (line) must have eleven fields. Some of those fields can be empty. Every field (even empty ones) must be enclosed in double-quotes.
 522     </p>
 523 <div class="literallayout"><p><br>
 524 &#160;&#160;&#160;&#160;&#160;&#160;Ex:<br>
 525 &#160;&#160;&#160;&#160;&#160;&#160;"America/Phoenix"&#160;&lt;-&#160;string&#160;enclosed&#160;in&#160;quotes<br>
 526 &#160;&#160;&#160;&#160;&#160;&#160;""&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&lt;-&#160;empty&#160;field<br>
 527 &#160;&#160;&#160;&#160;</p></div>
 528 <p>
 529   </p>
 530 <p>
 531     Some fields represent a length of time. The format of these fields must be:
 532     </p>
 533 <div class="literallayout"><p><br>
 534 &#160;&#160;&#160;&#160;&#160;&#160;"{+|-}hh:mm[:ss]"&#160;&lt;-&#160;length-of-time&#160;format<br>
 535 &#160;&#160;&#160;&#160;</p></div>
 536 <p>
 537     Where the plus or minus is mandatory and the seconds are optional.
 538   </p>
 539 <p>
 540     Since some time zones do not use daylight savings it is not always necessary for every field in a zone_spec to contain a value. All zone_specs must have at least ID and GMT offset. Zones that use daylight savings must have all fields filled except: STD ABBR, STD NAME, DST NAME. You should take note that DST ABBR is mandatory for zones that use daylight savings (see field descriptions for further details).
 541   </p>
 542 <a name="tz_database_fields"></a><h4>
 543 <a name="idp212286528"></a>Field Description/Details</h4>
 544 <p>
 545     </p>
 546 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
 547 <li class="listitem">
 548         ID
 549         <p>
 550           Contains the identifying string for the zone_spec. Any string will do as long as it's unique. No two ID's can be the same.
 551         </p>
 552 </li>
 553 <li class="listitem">
 554         STD ABBR
 555       </li>
 556 <li class="listitem">
 557         STD NAME
 558       </li>
 559 <li class="listitem">
 560         DST ABBR
 561       </li>
 562 <li class="listitem">
 563         DST NAME
 564         <p>
 565           These four are all the names and abbreviations used by the time zone being described. While any string will do in these fields, care should be taken. These fields hold the strings that will be used in the output of many of the local_time classes.
 566         </p>
 567 </li>
 568 <li class="listitem">
 569         GMT offset
 570         <p>
 571           This is the number of hours added to utc to get the local time before any daylight savings adjustments are made. Some examples are: America/New_York offset -5 hours, and Africa/Cairo offset +2 hours. The format must follow the length-of-time format described above.
 572         </p>
 573 </li>
 574 <li class="listitem">
 575         DST adjustment
 576         <p>
 577           The amount of time added to gmt_offset when daylight savings is in effect. The format must follow the length-of-time format described above.
 578         </p>
 579 <p>
 580           NOTE: more rule capabilities are needed - this portion of the tz_database is incomplete
 581         </p>
 582 </li>
 583 <li class="listitem">
 584         DST Start Date rule
 585         <p>
 586           This is a specially formatted string that describes the day of year in which the transition take place. It holds three fields of it's own, separated by semicolons.
 587           </p>
 588 <div class="orderedlist"><ol class="orderedlist" type="1">
 589 <li class="listitem">
 590               The first field indicates the "nth" weekday of the month. The possible values are: 1 (first), 2 (second), 3 (third), 4 (fourth), 5 (fifth), and -1 (last).
 591             </li>
 592 <li class="listitem">
 593               The second field indicates the day-of-week from 0-6 (Sun=0).
 594             </li>
 595 <li class="listitem">
 596               The third field indicates the month from 1-12 (Jan=1).
 597             </li>
 598 </ol></div>
 599 <p>
 600           Examples are: "-1;5;9"="Last Friday of September", "2;1;3"="Second Monday of March"
 601         </p>
 602 </li>
 603 <li class="listitem">
 604         Start time
 605         <p>
 606           Start time is the number of hours past midnight, on the day of the start transition, the transition takes place. More simply put, the time of day the transition is made (in 24 hours format). The format must follow the length-of-time format described above with the exception that it must always be positive.
 607         </p>
 608 </li>
 609 <li class="listitem">
 610         DST End date rule
 611         <p>
 612           See DST Start date rule. The difference here is this is the day daylight savings ends (transition to STD).
 613         </p>
 614 </li>
 615 <li class="listitem">
 616         End time
 617         <p>
 618           Same as Start time.
 619         </p>
 620 </li>
 621 </ul></div>
 622 <p>
 623   </p>
 624 </div>
 625 <div class="section">
 626 <div class="titlepage"><div><div><h3 class="title">
 627 <a name="date_time.local_time.custom_time_zone"></a>Custom Time Zone</h3></div></div></div>
 628 <a class="link" href="local_time.html#custom_time_zone_intro">Introduction</a> --
 629   <a class="link" href="local_time.html#custom_time_zone_header">Header</a> --
 630   <a class="link" href="local_time.html#custom_time_zone_constr">Construction</a> --
 631   <a class="link" href="local_time.html#custom_time_zone_accessors">Accessors</a> --
 632   <a class="link" href="local_time.html#custom_time_zone_dependents">Dependent Types</a><a name="custom_time_zone_intro"></a><h4>
 633 <a name="idp212307632"></a>Introduction</h4>
 634 <p>
 635     A custom_time_zone object is a set of data and rules that provide information about a time zone. Information such as the offset from UTC, it's name and abbreviation, as well as daylight savings rules, called <a class="link" href="local_time.html#date_time.local_time.dst_calc_rules">dst_calc_rules</a>. These rules are handled via a boost::shared_ptr&lt;dst_calc_rules&gt;. Not all time zones utilize daylight savings, therefore, time_zone objects can be used with a NULL-assigned shared_ptr.
 636   </p>
 637 <p>
 638     As a convenience, a typedef for shared_ptr&lt;dst_calc_rules&gt; is provided.
 639     </p>
 640 <pre class="programlisting">typedef boost::shared_ptr&lt;dst_calc_rules&gt; local_time::dst_calc_rule_ptr;</pre>
 641 <p>
 642   </p>
 643 <a name="date_time.local_time.custom_time_zone_ptr"></a><p>
 644     The time_zone objects are used via a boost::shared_ptr&lt;local_time::time_zone&gt;. As a convenience, a typedef for boost::shared_ptr&lt;local_time::time_zone&gt; is provided:
 645     </p>
 646 <pre class="programlisting">typedef boost::shared_ptr&lt;time_zone&gt; local_time::time_zone_ptr;</pre>
 647 <p>
 648   </p>
 649 <a name="custom_time_zone_header"></a><h4>
 650 <a name="idp212314528"></a>Header</h4>
 651 <p>
 652     The inclusion of a single header will bring in all boost::local_time types, functions, and IO operators.
 653     </p>
 654 <pre class="programlisting">#include "boost/date_time/local_time/local_time.hpp"</pre>
 655 <p>
 656   </p>
 657 <a name="custom_time_zone_constr"></a><h4>
 658 <a name="idp212317136"></a>Construction</h4>
 659 <p>
 660     Construction of a custom_time_zone is dependent on four objects: a
 661     <a class="link" href="posix_time.html#date_time.posix_time.time_duration" title="Time Duration">time_duration</a>, a <a class="link" href="local_time.html#time_zone_names">time_zone_names</a>, a <a class="link" href="local_time.html#dst_adjustment_offsets">dst_adjustment_offsets</a>, and a shared_ptr to a <a class="link" href="local_time.html#date_time.local_time.dst_calc_rules">dst_calc_rule</a>.
 662   </p>
 663 <p>
 664     </p>
 665 <div class="informaltable"><table class="table">
 666 <colgroup>
 667 <col>
 668 <col>
 669 </colgroup>
 670 <thead><tr>
 671 <th>Syntax</th>
 672 <th>Example</th>
 673 </tr></thead>
 674 <tbody><tr>
 675 <td valign="top"><pre class="screen">custom_time_zone(...)
 676   Parameters:
 677     <a class="link" href="local_time.html#time_zone_names">names</a>,
 678     <a class="link" href="posix_time.html#date_time.posix_time.time_duration" title="Time Duration">gmt_offset</a>,
 679     <a class="link" href="local_time.html#dst_adjustment_offsets">dst_offsets</a>,
 680     <a class="link" href="local_time.html#date_time.local_time.dst_calc_rules">dst_rules</a> </pre></td>
 681 <td>See <a class="link" href="examples.html#date_time.examples.simple_time_zone" title="Simple Time Zones">simple_time_zone</a> example for time_zone usage</td>
 682 </tr></tbody>
 683 </table></div>
 684 <p>
 685   </p>
 686 <a name="custom_time_zone_accessors"></a><h4>
 687 <a name="idp212332624"></a>Accessors</h4>
 688 <p>
 689     </p>
 690 <div class="informaltable"><table class="table">
 691 <colgroup>
 692 <col>
 693 <col>
 694 </colgroup>
 695 <thead>
 696 <tr>
 697 <th rowspan="2" valign="top">Syntax</th>
 698 <th>Description</th>
 699 </tr>
 700 <tr><th>Example</th></tr>
 701 </thead>
 702 <tbody>
 703 <tr>
 704 <td rowspan="2" valign="top"><pre class="screen">std::string dst_zone_abbrev()</pre></td>
 705 <td>Returns the daylight savings abbreviation for the represented time zone.</td>
 706 </tr>
 707 <tr><td><pre class="screen">nyc_zone_sh_ptr-&gt;dst_zone_abbrev();
 708 // "EDT"</pre></td></tr>
 709 <tr>
 710 <td rowspan="2" valign="top"><pre class="screen">std::string std_zone_abbrev()</pre></td>
 711 <td>Returns the standard abbreviation for the represented time zone.</td>
 712 </tr>
 713 <tr><td><pre class="screen">nyc_zone_sh_ptr-&gt;std_zone_abbrev();
 714 // "EST"</pre></td></tr>
 715 <tr>
 716 <td rowspan="2" valign="top"><pre class="screen">std::string dst_zone_name()</pre></td>
 717 <td>Returns the daylight savings name for the represented time zone.</td>
 718 </tr>
 719 <tr><td><pre class="screen">nyc_zone_sh_ptr-&gt;dst_zone_name();
 720 // "Eastern Daylight Time"</pre></td></tr>
 721 <tr>
 722 <td rowspan="2" valign="top"><pre class="screen">std::string std_zone_name()</pre></td>
 723 <td>Returns the standard name for the represented time zone.</td>
 724 </tr>
 725 <tr><td><pre class="screen">nyc_zone_sh_ptr-&gt;std_zone_name();
 726 // "Eastern Standard Time"</pre></td></tr>
 727 <tr>
 728 <td rowspan="2" valign="top"><pre class="screen">bool has_dst()</pre></td>
 729 <td>Returns true when custom_time_zone's shared_ptr to dst_calc_rules is not NULL.</td>
 730 </tr>
 731 <tr><td>
 732 <pre class="screen">nyc_zone_sh_ptr-&gt;has_dst();
 733 // true
 734 phx_zone_sh_ptr-&gt;has_dst();
 735 // false</pre>
 736             </td></tr>
 737 <tr>
 738 <td rowspan="2" valign="top"><pre class="screen">dst_local_start_time(...)
 739   Return Type:
 740     ptime
 741   Parameter:
 742     greg_year</pre></td>
 743 <td>The date and time daylight savings time begins in given year. Returns not_a_date_time if this zone has no daylight savings.</td>
 744 </tr>
 745 <tr><td><pre class="screen">nyc_ptr-&gt;dst_local_start_time(2004);
 746 // 2004-Apr-04 02:00</pre></td></tr>
 747 <tr>
 748 <td rowspan="2" valign="top"><pre class="screen">dst_local_end_time(...)
 749   Return Type:
 750     ptime
 751   Parameter:
 752     greg_year</pre></td>
 753 <td>The date and time daylight savings time ends in given year. Returns not_a_date_time if this zone has no daylight savings.</td>
 754 </tr>
 755 <tr><td><pre class="screen">nyc_ptr-&gt;dst_local_end_time(2004);
 756 // 2004-Oct-31 02:00</pre></td></tr>
 757 <tr>
 758 <td rowspan="2" valign="top"><pre class="screen">time_duration base_utc_offset()</pre></td>
 759 <td>The amount of time offset from UTC (typically in hours).</td>
 760 </tr>
 761 <tr><td><pre class="screen">nyc_ptr-&gt;base_utc_offset();
 762 // -05:00</pre></td></tr>
 763 <tr>
 764 <td rowspan="2" valign="top"><pre class="screen">time_duration dst_offset()</pre></td>
 765 <td>The amount of time shifted during daylight savings.</td>
 766 </tr>
 767 <tr><td><pre class="screen">nyc_zone_sh_ptr-&gt;dst_offset();
 768 // 01:00</pre></td></tr>
 769 <tr>
 770 <td rowspan="2" valign="top"><pre class="screen">std::string to_posix_string()</pre></td>
 771 <td>Returns a posix time zone string representation of this time_zone object. Depending on how the time_zone object was created, the date-spec format of the string will be in either 'M' notation or 'n' notation. Every possible date-spec that can be represented in 'J' notation can also be represented in 'n' notation. The reverse is not true so only 'n' notation is used for these types of date-specs. For a detailed description of a posix time zone string see <a class="link" href="local_time.html#date_time.local_time.posix_time_zone" title="Posix Time Zone">posix_time_zone</a>.</td>
 772 </tr>
 773 <tr><td><pre class="screen">nyc_ptr-&gt;to_posix_string();
 774 // "EST-05EDT+01,M4.1.0/02:00,M10.5.0/02:00"
 775 phx_ptr-&gt;to_posix_string();
 776 // "MST-07"
 777             </pre></td></tr>
 778 </tbody>
 779 </table></div>
 780 <p>
 781   </p>
 782 <a name="custom_time_zone_dependents"></a><h4>
 783 <a name="idp212375248"></a>Dependent Types</h4>
 784 <a class="link" href="local_time.html#time_zone_names">Time Zone Names</a> --
 785   <a class="link" href="local_time.html#dst_adjustment_offsets">Dst Adjustment Offsets</a> --
 786   <a class="link" href="local_time.html#date_time.local_time.dst_calc_rules">Daylight Savings Calc Rules</a><a name="time_zone_names"></a><h4>
 787 <a name="idp212379120"></a>Time Zone Names</h4>
 788 <p>
 789     The time_zone_names_base type is an immutable template class of four strings. One each for the name and abbreviation in standard time and daylight savings time. The time_zone_names type is a typedef of time_zone_names_base&lt;char&gt;.
 790   </p>
 791 <p>
 792     </p>
 793 <div class="informaltable"><table class="table">
 794 <colgroup>
 795 <col>
 796 <col>
 797 </colgroup>
 798 <thead>
 799 <tr>
 800 <th rowspan="2" valign="top">Syntax</th>
 801 <th>Description</th>
 802 </tr>
 803 <tr><th>Example</th></tr>
 804 </thead>
 805 <tbody>
 806 <tr>
 807 <td rowspan="2" valign="top"><pre class="screen">time_zone_names(...)
 808   Parameters:
 809     string std_name
 810     string std_abbrev
 811     string dst_name
 812     string dst_abbrev</pre></td>
 813 <td>The only constructor, all four strings must be provided.</td>
 814 </tr>
 815 <tr><td>
 816 <pre class="screen">string sn("Eastern Standard Time");
 817 string sa("EST");
 818 string dn("Eastern Daylight Time");
 819 string da("EDT");
 820 time_zone_names nyc_names(sn, sa,
 821                           dn, da);</pre>
 822             </td></tr>
 823 <tr>
 824 <td rowspan="2" valign="top"><pre class="screen">std::string std_zone_name()</pre></td>
 825 <td>Returns the standard zone name</td>
 826 </tr>
 827 <tr><td><pre class="screen">nyc_names.std_zone_name();
 828 // "Eastern Standard Time"</pre></td></tr>
 829 <tr>
 830 <td rowspan="2" valign="top"><pre class="screen">std::string std_zone_abbrev()</pre></td>
 831 <td>Returns the standard zone abbreviation</td>
 832 </tr>
 833 <tr><td><pre class="screen">nyc_names.std_zone_abbrev();
 834 // "EST"</pre></td></tr>
 835 <tr>
 836 <td rowspan="2" valign="top"><pre class="screen">std::string dst_zone_name()</pre></td>
 837 <td>Returns the daylight savings zone name</td>
 838 </tr>
 839 <tr><td><pre class="screen">nyc_names.std_zone_name();
 840 // "Eastern Daylight Time"</pre></td></tr>
 841 <tr>
 842 <td rowspan="2" valign="top"><pre class="screen">std::string dst_zone_abbrev()</pre></td>
 843 <td>Returns the daylight savings zone abbreviation</td>
 844 </tr>
 845 <tr><td><pre class="screen">nyc_names.std_zone_abbrev();
 846 // "EDT"</pre></td></tr>
 847 </tbody>
 848 </table></div>
 849 <p>
 850   </p>
 851 <a name="dst_adjustment_offsets"></a><h4>
 852 <a name="idp212403408"></a>Dst Adjustment Offsets</h4>
 853 <p>
 854     The dst_adjustment_offsets type is a collection of three <a class="link" href="posix_time.html#date_time.posix_time.time_duration" title="Time Duration">time_duration</a> objects.
 855   </p>
 856 <p>
 857     </p>
 858 <div class="informaltable"><table class="table">
 859 <colgroup>
 860 <col>
 861 <col>
 862 </colgroup>
 863 <thead>
 864 <tr>
 865 <th rowspan="2" valign="top">Syntax</th>
 866 <th>Description</th>
 867 </tr>
 868 <tr><th>Example</th></tr>
 869 </thead>
 870 <tbody>
 871 <tr>
 872 <td rowspan="2" valign="top"><pre class="screen">dst_adjustment_offsets(...)
 873   Parameters:
 874     time_duration dst_adjust
 875     time_duration start_offset
 876     time_duration end_offset</pre></td>
 877 <td>The first time_duration is the daylight savings adjustment. The second is the time which daylight savings starts on the start day. The third is the time daylight savings ends on the ending day.</td>
 878 </tr>
 879 <tr><td><pre class="screen">
 880 dst_adjustment_offsets(hours(1),
 881                        hours(2),
 882                        hours(2));</pre></td></tr>
 883 </tbody>
 884 </table></div>
 885 <p>
 886   </p>
 887 <a name="date_time.local_time.dst_calc_rules"></a><h4>
 888 <a name="idp212414720"></a>Daylight Savings Calc Rules</h4>
 889 <p>
 890     Daylight savings calc rules, named dst_calc_rules, are a series of objects that group appropriate <a class="link" href="gregorian.html#date_time.gregorian.date_algorithms" title="Date Generators/Algorithms">date_generators</a> together to form rule sets. The individual rules objects are used via dst_calc_rule_ptr.
 891   </p>
 892 <p>
 893     For a complete example of all five dst_calc_rule types, see: <a class="link" href="examples.html#date_time.examples.calc_rules" title="Daylight Savings Calc Rules">calc_rules example</a>.
 894   </p>
 895 <p>
 896     </p>
 897 <div class="informaltable"><table class="table">
 898 <colgroup>
 899 <col>
 900 <col>
 901 </colgroup>
 902 <thead><tr>
 903 <th>Syntax</th>
 904 <th>Description</th>
 905 </tr></thead>
 906 <tbody>
 907 <tr>
 908 <td valign="top"><pre class="screen">partial_date_dst_rule(...)
 909   Parameters:
 910     start_rule
 911     end_rule</pre></td>
 912 <td>Both the start and end rules are of type gregorian::partial_date.</td>
 913 </tr>
 914 <tr>
 915 <td valign="top"><pre class="screen">first_last_dst_rule(...)
 916   Parameters:
 917     start_rule
 918     end_rule</pre></td>
 919 <td>The DST start rule is of type gregorian::first_day_of_the_week_in_month and the end rule is of type gregorian::last_day_of_the_week_in_month.</td>
 920 </tr>
 921 <tr>
 922 <td valign="top"><pre class="screen">last_last_dst_rule(...)
 923   Parameters:
 924     start_rule
 925     end_rule</pre></td>
 926 <td>Both the start and end rules are of type gregorian::last_day_of_the_week_in_month.</td>
 927 </tr>
 928 <tr>
 929 <td valign="top"><pre class="screen">nth_last_dst_rule(...)
 930   Parameters:
 931     start_rule
 932     end_rule</pre></td>
 933 <td>The DST start rule is of type gregorian::nth_day_of_the_week_in_month and the end rule is of type gregorian::last_day_of_the_week_in_month.</td>
 934 </tr>
 935 <tr>
 936 <td valign="top">
 937 <pre class="screen">nth_kday_dst_rule(...)
 938   Parameters:
 939     start_rule
 940     end_rule)
 941 (see note* below)</pre>
 942             </td>
 943 <td>Both rules are of type gregorian::nth_day_of_the_week_in_month.</td>
 944 </tr>
 945 </tbody>
 946 </table></div>
 947 <p>
 948     </p>
 949 <p>
 950       * Note: The name "nth_kday_dst_rule" is a bit cryptic. Therefore, a more descriptive name, "nth_day_of_the_week_in_month_dst_rule", is also provided.
 951     </p>
 952 <p>
 953   </p>
 954 </div>
 955 <div class="section">
 956 <div class="titlepage"><div><div><h3 class="title">
 957 <a name="date_time.local_time.local_date_time"></a>Local Date Time</h3></div></div></div>
 958 <a class="link" href="local_time.html#local_date_time_intro">Introduction</a> --
 959   <a class="link" href="local_time.html#local_date_time_header">Header</a> --
 960   <a class="link" href="local_time.html#local_date_time_clock_constr">Construct From Clock</a> --
 961   <a class="link" href="local_time.html#local_date_time_constr">Construction</a> --
 962   <a class="link" href="local_time.html#local_date_time_accessors">Accessors</a> --
 963   <a class="link" href="local_time.html#local_date_time_operators">Operators</a> --
 964   <a class="link" href="local_time.html#local_date_time_tm_func">Struct tm Functions</a><a name="local_date_time_intro"></a><h4>
 965 <a name="idp212441504"></a>Introduction</h4>
 966 <p>
 967     A local_date_time object is a point in time and an associated time zone. The time is represented internally as UTC.
 968   </p>
 969 <a name="local_date_time_header"></a><h4>
 970 <a name="idp212443344"></a>Header</h4>
 971 <p>
 972     The inclusion of a single header will bring in all boost::local_time types,
 973 functions, and IO operators.
 974     </p>
 975 <pre class="programlisting">
 976       #include "boost/date_time/local_time/local_time.hpp"
 977     </pre>
 978 <p>
 979   </p>
 980 <a name="local_date_time_clock_constr"></a><h4>
 981 <a name="idp212446016"></a>Construct From Clock</h4>
 982 <p>
 983     Creation of a local_date_time object from clock is possible with either second, or sub second resolution.
 984   </p>
 985 <p>
 986     </p>
 987 <div class="informaltable"><table class="table">
 988 <colgroup>
 989 <col>
 990 <col>
 991 </colgroup>
 992 <thead><tr>
 993 <th>Syntax</th>
 994 <th>Example</th>
 995 </tr></thead>
 996 <tbody>
 997 <tr>
 998 <td valign="top"><pre class="screen">local_microsec_clock(...)
 999   Return Type:
1000     local_date_time
1001   Parameter:
1002     time_zone_ptr</pre></td>
1003 <td>
1004 <pre class="screen">time_zone_ptr zone(
1005   new posix_time_zone("MST-07")
1006 );
1007 local_date_time ldt =
1008   local_microsec_clock::local_time(
1009     zone);</pre>
1010             </td>
1011 </tr>
1012 <tr>
1013 <td valign="top"><pre class="screen">local_sec_clock(...)
1014   Return Type:
1015     local_date_time
1016   Parameter:
1017     time_zone_ptr</pre></td>
1018 <td>
1019 <pre class="screen">time_zone_ptr zone(
1020   new posix_time_zone("MST-07")
1021 );
1022 local_date_time ldt =
1023   local_sec_clock::local_time(zone);</pre>
1024             </td>
1025 </tr>
1026 </tbody>
1027 </table></div>
1028 <p>
1029   </p>
1030 <a name="local_date_time_constr"></a><h4>
1031 <a name="idp212456672"></a>Construction</h4>
1032 <p>
1033     Construction of a local_date_time object can be done with a ptime and a time_zone_ptr where the ptime represents UTC time. Construction with a wall-clock representation takes the form of a date, a time_duration, a time_zone_ptr, and a fourth parameter that addresses the following complication.
1034   </p>
1035 <p>
1036     Construction from a wall-clock rep may result in differing shifts for a particular time zone, depending on daylight savings rules for that zone. This means it is also possible to create a local_date_time with a non-existent, or duplicated, UTC representation. These cases occur during the forward shift in time that is the transition into daylight savings and during the backward shift that is the transition out of daylight savings. The user has two options for handling these cases: a bool flag that states if the time is daylight savings, or an enum that states what to do when either of these cases are encountered.
1037   </p>
1038 <p>
1039     The bool flag is ignored when the given time_zone has no daylight savings specification. When the daylight savings status of a given time label is calculated and it does not match the flag, a <code class="computeroutput">local_time::dst_not_valid</code> exception is thrown. If a time label is invalid (does not exist), a <code class="computeroutput">local_time::time_label_invalid</code> exception is thrown.
1040   </p>
1041 <p>
1042     There are two elements in the <code class="computeroutput">local_date_time::DST_CALC_OPTIONS</code> enum: <code class="computeroutput">EXCEPTION_ON_ERROR</code> and <code class="computeroutput">NOT_DATE_TIME_ON_ERROR</code>. The possible exceptions thrown are a <code class="computeroutput">local_time::ambiguous_result</code> or a <code class="computeroutput">local_time::time_label_invalid</code>. The <code class="computeroutput">NOT_DATE_TIME_ON_ERROR</code> sets the time value to the special value <code class="computeroutput">local_time::not_a_date_time</code> in the event of either a invalid or an ambiguous time label.
1043   </p>
1044 <p>
1045     </p>
1046 <div class="informaltable"><table class="table">
1047 <colgroup>
1048 <col>
1049 <col>
1050 </colgroup>
1051 <thead>
1052 <tr>
1053 <th rowspan="2">Syntax</th>
1054 <th>Description</th>
1055 </tr>
1056 <tr><th>Example</th></tr>
1057 </thead>
1058 <tbody>
1059 <tr>
1060 <td rowspan="2" valign="top"><pre class="screen">local_date_time(...)
1061   Parameters:
1062     posix_time::ptime
1063     time_zone_ptr</pre></td>
1064 <td>The given time is expected to be UTC. Therefore, the given time will be adjusted according to the offset described in the time zone.</td>
1065 </tr>
1066 <tr><td>
1067 <pre class="screen">
1068 // 3am, 2004-Nov-05 local time
1069 ptime pt(date(2004,Nov,5),
1070          hours(10));
1071 time_zone_ptr zone(
1072   new posix_time_zone("MST-07"));
1073 local_date_time az(pt, zone);</pre>
1074             </td></tr>
1075 <tr>
1076 <td rowspan="2" valign="top"><pre class="screen">local_date_time(...)
1077   Parameters:
1078     date
1079     time_duration
1080     time_zone_ptr
1081     bool</pre></td>
1082 <td>The passed time information understood to be in the passed tz. The DST flag must be passed to indicate whether the time is in daylight savings or not. May throw a <code class="computeroutput">dst_not_valid</code> or <code class="computeroutput">time_label_invalid</code> exception.</td>
1083 </tr>
1084 <tr><td>
1085 <pre class="screen">date d(2004,Nov,5);
1086 time_duration td(5,0,0,0);
1087 string z("PST-8PDT,M4.1.0,M10.1.0")
1088 time_zone_ptr zone(
1089   new posix_time_zone(z));
1090 local_date_time nyc(d, td,
1091                     zone, false);</pre>
1092             </td></tr>
1093 <tr>
1094 <td rowspan="2" valign="top"><pre class="screen">local_date_time(...)
1095   Parameters:
1096     date
1097     time_duration
1098     time_zone_ptr
1099     DST_CALC_OPTIONS</pre></td>
1100 <td>The passed time information understood to be in the passed tz. The DST flag is calculated according to the specified rule. May throw a <code class="computeroutput">ambiguous_result</code> or <code class="computeroutput">time_label_invalid</code> exception.</td>
1101 </tr>
1102 <tr><td>
1103 <pre class="screen">date d(2004,Nov,5);
1104 time_duration td(5,0,0,0);
1105 string z("PST-8PDT,M4.1.0,M10.1.0")
1106 time_zone_ptr zone(
1107   new posix_time_zone(z));
1108 local_date_time nyc(d, td, zone,
1109   NOT_DATE_TIME_ON_ERROR);</pre>
1110             </td></tr>
1111 <tr>
1112 <td rowspan="2" valign="top"><pre class="screen">local_date_time(local_date_time);</pre></td>
1113 <td>Copy Constructor.</td>
1114 </tr>
1115 <tr><td><pre class="screen">local_date_time az_2(az);</pre></td></tr>
1116 <tr>
1117 <td rowspan="2" valign="top"><pre class="screen">local_date_time(...)
1118   Parameters:
1119     special_values
1120     time_zone_ptr</pre></td>
1121 <td>Special Values constructor.</td>
1122 </tr>
1123 <tr><td>
1124 <pre class="screen">time_zone_ptr zone(
1125   new posix_time_zone("MST-07")
1126 );
1127 local_date_time nadt(not_a_date_time,
1128                      zone);
1129 // default NULL time_zone_ptr
1130 local_date_time nadt(pos_infin);</pre>
1131             </td></tr>
1132 </tbody>
1133 </table></div>
1134 <p>
1135   </p>
1136 <a name="local_date_time_accessors"></a><h4>
1137 <a name="idp212493472"></a>Accessors</h4>
1138 <p>
1139     </p>
1140 <div class="informaltable"><table class="table">
1141 <colgroup>
1142 <col>
1143 <col>
1144 </colgroup>
1145 <thead>
1146 <tr>
1147 <th rowspan="2" valign="top">Syntax</th>
1148 <th>Description</th>
1149 </tr>
1150 <tr><th>Example</th></tr>
1151 </thead>
1152 <tbody>
1153 <tr>
1154 <td rowspan="2" valign="top"><pre class="screen">time_zone_ptr zone()</pre></td>
1155 <td>Returns associated time_zone object via a time_zone_ptr</td>
1156 </tr>
1157 <tr><td><pre class="screen"></pre></td></tr>
1158 <tr>
1159 <td rowspan="2" valign="top"><pre class="screen">bool is_dst()</pre></td>
1160 <td>Determines if time value is in DST for associated zone.</td>
1161 </tr>
1162 <tr><td>&#160;</td></tr>
1163 <tr>
1164 <td rowspan="2" valign="top"><pre class="screen">ptime utc_time()</pre></td>
1165 <td>Converts the local time value to a UTC value.</td>
1166 </tr>
1167 <tr><td>
1168 <pre class="screen">ptime pt(date(2004,Nov,5),
1169          hours(10));
1170 time_zone_ptr zone(
1171   new posix_time_zone("MST-07"));
1172 local_date_time az(pt, zone);
1173 az.utc_time(); // 10am 2004-Nov-5</pre>
1174             </td></tr>
1175 <tr>
1176 <td rowspan="2" valign="top"><pre class="screen">ptime local_time()</pre></td>
1177 <td>Returns the local time for this object (Wall-clock).</td>
1178 </tr>
1179 <tr><td><pre class="screen">ptime pt(date(2004,Nov,5),
1180          hours(10));
1181 time_zone_ptr zone(
1182   new posix_time_zone("MST-07"));
1183 local_date_time az(pt, zone);
1184 az.utc_time(); // 10am 2004-Nov-5
1185 az.local_time(); // 3am 2004-Nov-5</pre></td></tr>
1186 <tr>
1187 <td rowspan="2" valign="top"><pre class="screen">local_time_in(...)
1188   Return Type:
1189     local_date_time
1190   Parameters:
1191     time_zone_ptr
1192     time_duration</pre></td>
1193 <td>Returns a local_date_time representing the same UTC time as calling object, plus optional time_duration, with given time zone.</td>
1194 </tr>
1195 <tr><td>
1196 <pre class="screen">local_date_time nyc = az.local_time_in(nyc_zone);
1197 // nyc == 7am 2004-Nov-5</pre>
1198             </td></tr>
1199 <tr>
1200 <td rowspan="2" valign="top"><pre class="screen">bool is_infinity() const</pre></td>
1201 <td>Returns true if local_date_time is either positive or negative infinity</td>
1202 </tr>
1203 <tr><td><pre class="screen">local_date_time ldt(pos_infin);
1204 ldt.is_infinity(); // --&gt; true</pre></td></tr>
1205 <tr>
1206 <td rowspan="2" valign="top"><pre class="screen">bool is_neg_infinity() const</pre></td>
1207 <td>Returns true if local_date_time is negative infinity</td>
1208 </tr>
1209 <tr><td><pre class="screen">local_date_time ldt(neg_infin);
1210 ldt.is_neg_infinity(); // --&gt; true</pre></td></tr>
1211 <tr>
1212 <td rowspan="2" valign="top"><pre class="screen">bool is_pos_infinity() const</pre></td>
1213 <td>Returns true if local_date_time is positive infinity</td>
1214 </tr>
1215 <tr><td><pre class="screen">local_date_time ldt(neg_infin);
1216 ldt.is_pos_infinity(); // --&gt; true</pre></td></tr>
1217 <tr>
1218 <td rowspan="2" valign="top"><pre class="screen">bool is_not_a_date_time() const</pre></td>
1219 <td>Returns true if value is not a date</td>
1220 </tr>
1221 <tr><td><pre class="screen">local_date_time ldt(not_a_date_time);
1222 ldt.is_not_a_date_time(); // --&gt; true</pre></td></tr>
1223 <tr>
1224 <td rowspan="2" valign="top"><pre class="screen">bool is_special() const</pre></td>
1225 <td>Returns true if local_date_time is any <code class="computeroutput">special_value</code>
1226 </td>
1227 </tr>
1228 <tr><td><pre class="screen">local_date_time ldt(pos_infin);
1229 local_date_time ldt2(not_a_date_time);
1230 time_zone_ptr
1231   mst(new posix_time_zone("MST-07"));
1232 local_date_time
1233   ldt3(local_sec_clock::local_time(mst));
1234 ldt.is_special(); // --&gt; true
1235 ldt2.is_special(); // --&gt; true
1236 ldt3.is_special(); // --&gt; false</pre></td></tr>
1237 </tbody>
1238 </table></div>
1239 <p>
1240   </p>
1241 <a name="local_date_time_operators"></a><h4>
1242 <a name="idp212534624"></a>Operators</h4>
1243 <div class="informaltable"><table class="table">
1244 <colgroup>
1245 <col>
1246 <col>
1247 </colgroup>
1248 <thead>
1249 <tr>
1250 <th rowspan="2" valign="top">Syntax</th>
1251 <th>Description</th>
1252 </tr>
1253 <tr><th>Example</th></tr>
1254 </thead>
1255 <tbody>
1256 <tr>
1257 <td rowspan="2" valign="top"><pre class="screen">operator&lt;&lt;</pre></td>
1258 <td>Output streaming operator. This operator is part of the v1.33 IO addition to date_time. For complete details on this feature see <a class="link" href="date_time_io.html" title="Date Time Input/Output">Date Time IO</a>. The default output is shown in this example.</td>
1259 </tr>
1260 <tr><td><pre class="screen">
1261 time_zone_ptr zone(new posix_time_zone("MST-07");
1262 local_date_time ldt(date(2005,Jul,4),
1263                     hours(20),
1264                     false);
1265 std::cout &lt;&lt; ldt &lt;&lt; std::endl;
1266 // "2005-Jul-04 20:00:00 MST"
1267           </pre></td></tr>
1268 <tr>
1269 <td rowspan="2" valign="top"><pre class="screen">operator&gt;&gt;</pre></td>
1270 <td>Input streaming operator. This operator is part of the v1.33 IO addition to date_time. For complete details on this feature see <a class="link" href="date_time_io.html" title="Date Time Input/Output">Date Time IO</a>. At this time, <code class="computeroutput">local_date_time</code> objects can only be streamed in with a Posix Time Zone string. A complete description of a Posix Time Zone string can be found in the documentation for the <a class="link" href="local_time.html#posix_time_zone_intro">posix_time_zone</a> class.</td>
1271 </tr>
1272 <tr><td><pre class="screen">stringstream ss;
1273 ss.str("2005-Jul-04 20:00:00 MST-07");
1274 ss &gt;&gt; ldt;
1275           </pre></td></tr>
1276 <tr>
1277 <td rowspan="2" valign="top"><pre class="screen">operator==, operator!=,
1278 operator&gt;, operator&lt;,
1279 operator&gt;=, operator&lt;=</pre></td>
1280 <td>A full complement of comparison operators</td>
1281 </tr>
1282 <tr><td><pre class="screen">ldt1 == ldt2, etc</pre></td></tr>
1283 <tr>
1284 <td rowspan="2" valign="top"><pre class="screen">operator+, operator+=,
1285 operator-, operator-=</pre></td>
1286 <td>Addition, subtraction, and shortcut operators for <code class="computeroutput">local_date_time</code> and date duration types. These include: <code class="computeroutput">days</code>, <code class="computeroutput">months</code>, and <code class="computeroutput">years</code>.</td>
1287 </tr>
1288 <tr><td><pre class="screen">ldt + days(5), etc</pre></td></tr>
1289 <tr>
1290 <td rowspan="2" valign="top"><pre class="screen">operator+, operator+=,
1291 operator-, operator-=</pre></td>
1292 <td>Addition, subtraction, and shortcut operators for <code class="computeroutput">local_date_time</code> and <code class="computeroutput">time_duration</code>.</td>
1293 </tr>
1294 <tr><td><pre class="screen">ldt + hours(5), etc</pre></td></tr>
1295 </tbody>
1296 </table></div>
1297 <a name="local_date_time_tm_func"></a><h4>
1298 <a name="idp212565552"></a>Struct tm Functions</h4>
1299 <p>Function for converting a <code class="computeroutput">local_date_time</code> object to a <code class="computeroutput">tm</code> struct is provided.</p>
1300 <div class="informaltable"><table class="table">
1301 <colgroup>
1302 <col>
1303 <col>
1304 </colgroup>
1305 <thead>
1306 <tr>
1307 <th rowspan="2" valign="top">Syntax</th>
1308 <th>Description</th>
1309 </tr>
1310 <tr><th>Example</th></tr>
1311 </thead>
1312 <tbody>
1313 <tr>
1314 <td rowspan="2" valign="top"><pre class="screen">tm to_tm(local_date_time)</pre></td>
1315 <td>A function for converting a <code class="computeroutput">local_date_time</code> object to a <code class="computeroutput">tm</code> struct.</td>
1316 </tr>
1317 <tr><td>
1318 <pre class="screen">
1319 // 6am, 2005-Jul-05 local time
1320 std::string z("EST-05EDT,M4.1.0,M10.1.0");
1321 ptime pt(date(2005,Jul,5),
1322          hours(10));
1323 time_zone_ptr zone( new posix_time_zone(z));
1324 local_date_time ldt(pt, zone);
1325 tm ldt_tm = to_tm(ldt);
1326 /* tm_year =&gt; 105
1327    tm_mon  =&gt; 6
1328    tm_mday =&gt; 5
1329    tm_wday =&gt; 2 (Tuesday)
1330    tm_yday =&gt; 185
1331    tm_hour =&gt; 6
1332    tm_min  =&gt; 0
1333    tm_sec  =&gt; 0
1334    tm_isddst =&gt; 1 */</pre>
1335           </td></tr>
1336 </tbody>
1337 </table></div>
1338 </div>
1339 <div class="section">
1340 <div class="titlepage"><div><div><h3 class="title">
1341 <a name="date_time.local_time.local_time_period"></a>Local Time Period</h3></div></div></div>
1342 <a class="link" href="local_time.html#local_time_period_intro">Introduction</a> --
1343   <a class="link" href="local_time.html#local_time_period_header">Header</a> --
1344   <a class="link" href="local_time.html#local_time_period_constr">Construction</a> --
1345   <a class="link" href="local_time.html#local_time_period_accessors">Accessors</a> --
1346   <a class="link" href="local_time.html#local_time_period_operators">Operators</a><a name="local_time_period_intro"></a><h4>
1347 <a name="idp212585104"></a>Introduction</h4>
1348 <p>
1349     The class <code class="computeroutput">boost::local_time::local_time_period</code> provides direct representation for ranges between two local times. Periods provide the ability to simplify some types of calculations by simplifying the conditional logic of the program.
1350   </p>
1351 <p>
1352     A period that is created with beginning and end points being equal, or with a duration of zero, is known as a zero length period. Zero length periods are considered invalid (it is perfectly legal to construct an invalid period). For these periods, the <code class="computeroutput">last</code> point will always be one unit less that the <code class="computeroutput">begin</code> point.
1353   </p>
1354 <a name="local_time_period_header"></a><h4>
1355 <a name="idp212589936"></a>Header</h4>
1356 <p>
1357     </p>
1358 <pre class="programlisting">#include "boost/date_time/local_time/local_time.hpp" //include all types plus i/o
1359 or
1360 #include "boost/date_time/local_time/local_time_types.hpp" //no i/o just types</pre>
1361 <p>
1362   </p>
1363 <a name="local_time_period_constr"></a><h4>
1364 <a name="idp212592560"></a>Construction</h4>
1365 <p>
1366     </p>
1367 <div class="informaltable"><table class="table">
1368 <colgroup>
1369 <col>
1370 <col>
1371 </colgroup>
1372 <thead>
1373 <tr>
1374 <th rowspan="2" valign="top">Syntax</th>
1375 <th>Description</th>
1376 </tr>
1377 <tr><th>Example</th></tr>
1378 </thead>
1379 <tbody>
1380 <tr>
1381 <td rowspan="2" valign="top"><pre class="screen">local_time_period(...)
1382   Parameters:
1383     local_date_time beginning
1384     local_date_time end</pre></td>
1385 <td> Create a period as [begin, end). If end is &lt;= begin then the period will be defined as invalid.</td>
1386 </tr>
1387 <tr><td>
1388 <pre class="screen">time_zone_ptr
1389   zone(new posix_time_zone("MST-07"));
1390 local_date_time
1391   beg(ptime(date(2005,Jan,1),hours(0)), zone);
1392 local_date_time
1393   end(ptime(date(2005,Feb,1),hours(0)), zone);
1394 // period for the entire month of Jan 2005
1395 local_time_period ltp(beg, end);</pre>
1396             </td></tr>
1397 <tr>
1398 <td rowspan="2" valign="top"><pre class="screen">local_time_period(...)
1399   Parameters:
1400     local_date_time beginning
1401     time_duration length</pre></td>
1402 <td>Create a period as [begin, begin+len) where end would be begin+len. If len is &lt;= zero then the period will be defined as invalid.</td>
1403 </tr>
1404 <tr><td>
1405 <pre class="screen">time_zone_ptr
1406   zone(new posix_time_zone("MST-07"));
1407 local_date_time
1408   beg(ptime(date(2005,Jan,1),hours(0)), zone);
1409 // period for the whole day of 2005-Jan-01
1410 local_time_period ltp(beg, hours(24));</pre>
1411             </td></tr>
1412 <tr>
1413 <td rowspan="2" valign="top"><pre class="screen">local_time_period(local_time_period rhs)</pre></td>
1414 <td>Copy constructor</td>
1415 </tr>
1416 <tr><td><pre class="screen">local_time_period ltp1(ltp);</pre></td></tr>
1417 </tbody>
1418 </table></div>
1419 <p>
1420   </p>
1421 <a name="local_time_period_accessors"></a><h4>
1422 <a name="idp212610048"></a>Accessors</h4>
1423 <p>
1424     </p>
1425 <div class="informaltable"><table class="table">
1426 <colgroup>
1427 <col>
1428 <col>
1429 </colgroup>
1430 <thead>
1431 <tr>
1432 <th rowspan="2" valign="top">Syntax</th>
1433 <th>Description</th>
1434 </tr>
1435 <tr><th>Example</th></tr>
1436 </thead>
1437 <tbody>
1438 <tr>
1439 <td rowspan="2" valign="top"><pre class="screen">local_date_time begin()</pre></td>
1440 <td>Return first local_date_time of the period.</td>
1441 </tr>
1442 <tr><td>
1443 <pre class="screen">time_zone_ptr
1444   zone(new posix_time_zone("MST-07"));
1445 local_date_time
1446   ldt((ptime(date(2005,Jan,1)),hours(0)), zone);
1447 local_time_period ltp(ldt, hours(2));
1448 ltp.begin(); // =&gt; 2005-Jan-01 00:00:00</pre>
1449             </td></tr>
1450 <tr>
1451 <td rowspan="2" valign="top"><pre class="screen">local_date_time last()</pre></td>
1452 <td>Return last local_date_time in the period</td>
1453 </tr>
1454 <tr><td>
1455 <pre class="screen">time_zone_ptr
1456   zone(new posix_time_zone("MST-07"));
1457 local_date_time
1458   ldt((ptime(date(2005,Jan,1),hours(0))), zone);
1459 local_time_period ltp(ldt, hours(2));
1460 ltp.last(); // =&gt; 2005-Jan-01 01:59:59.999999999</pre>
1461             </td></tr>
1462 <tr>
1463 <td rowspan="2" valign="top"><pre class="screen">local_date_time end()</pre></td>
1464 <td>Return one past the last in period</td>
1465 </tr>
1466 <tr><td>
1467 <pre class="screen">time_zone_ptr
1468   zone(new posix_time_zone("MST-07"));
1469 local_date_time
1470   ldt((ptime(date(2005,Jan,1),hours(0))), zone);
1471 local_time_period ltp(ldt, hours(2));
1472 ltp.end(); // =&gt; 2005-Jan-01 02:00:00</pre>
1473             </td></tr>
1474 <tr>
1475 <td rowspan="2" valign="top"><pre class="screen">time_duration length()</pre></td>
1476 <td>Return the length of the local_time period.</td>
1477 </tr>
1478 <tr><td>
1479 <pre class="screen">time_zone_ptr
1480   zone(new posix_time_zone("MST-07"));
1481 local_date_time
1482   ldt((ptime(date(2005,Jan,1),hours(0))), zone);
1483 local_time_period ltp(ldt, hours(2));
1484 ltp.length(); // =&gt; 02:00:00</pre>
1485             </td></tr>
1486 <tr>
1487 <td rowspan="2" valign="top"><pre class="screen">bool is_null()</pre></td>
1488 <td>True if period is not well formed. eg: end less than or equal to begin.</td>
1489 </tr>
1490 <tr><td>
1491 <pre class="screen">time_zone_ptr
1492   zone(new posix_time_zone("MST-07"));
1493 local_date_time
1494   beg((ptime(date(2005,Feb,1),hours(0))), zone);
1495 local_date_time
1496   end((ptime(date(2005,Jan,1),hours(0))), zone);
1497 local_time_period ltp(beg, end);
1498 ltp.is_null(); // =&gt; true</pre>
1499             </td></tr>
1500 <tr>
1501 <td rowspan="2" valign="top"><pre class="screen">bool contains(local_date_time)</pre></td>
1502 <td>True if local_date_time is within the period. Zero length periods cannot contain any points</td>
1503 </tr>
1504 <tr><td><pre class="screen">time_zone_ptr
1505   zone(new posix_time_zone("MST-07"));
1506 local_date_time
1507   beg((ptime(date(2005,Jan,1),hours(0))), zone);
1508 local_date_time
1509   end((ptime(date(2005,Feb,1),hours(0))), zone);
1510 local_time_period jan_mst(beg, end);
1511
1512 local_date_time
1513 ldt((ptime(date(2005,Jan,15),hours(12))), zone);
1514 jan_mst.contains(ldt); // =&gt; true
1515
1516 local_time_period zero(beg, beg);
1517 zero.contains(beg); // false</pre></td></tr>
1518 <tr>
1519 <td rowspan="2" valign="top"><pre class="screen">bool contains(local_time_period)</pre></td>
1520 <td>True if period is within the period</td>
1521 </tr>
1522 <tr><td><pre class="screen">// using jan_mst period from previous example
1523
1524 local_date_time
1525   beg((ptime(date(2005,Jan,7),hours(0))), zone);
1526 local_time_period ltp(beg, hours(24));
1527
1528 jan_mst.contains(ltp); // =&gt; true</pre></td></tr>
1529 <tr>
1530 <td rowspan="2" valign="top"><pre class="screen">bool intersects(local_time_period)</pre></td>
1531 <td> True if periods overlap</td>
1532 </tr>
1533 <tr><td><pre class="screen">// using jan_mst period from previous example
1534
1535 local_date_time
1536   beg((ptime(date(2005,Jan,7),hours(0))), zone);
1537 local_date_time
1538   end((ptime(date(2005,Feb,7),hours(0))), zone);
1539 local_time_period ltp(beg, end);
1540
1541 jan_mst.intersects(ltp); // =&gt; true</pre></td></tr>
1542 <tr>
1543 <td rowspan="2" valign="top"><pre class="screen">local_time_period intersection(local_time_period)</pre></td>
1544 <td>Calculate the intersection of 2 periods. Null if no intersection.</td>
1545 </tr>
1546 <tr><td><pre class="screen">// using jan_mst period from previous example
1547
1548 local_date_time
1549   beg((ptime(date(2005,Jan,7),hours(0))), zone);
1550 local_date_time
1551   end((ptime(date(2005,Feb,7),hours(0))), zone);
1552 local_time_period ltp(beg, end);
1553
1554 local_time_period res(jan_mst.intersection(ltp));
1555 // res =&gt; 2005-Jan-07 00:00:00 through
1556 // 2005-Jan-31 23:59:59.999999999 (inclusive)</pre></td></tr>
1557 <tr>
1558 <td rowspan="2" valign="top"><pre class="screen">local_time_period merge(local_time_period)</pre></td>
1559 <td>Returns union of two periods. Null if no intersection.</td>
1560 </tr>
1561 <tr><td><pre class="screen">// using jan_mst period from previous example
1562
1563 local_date_time
1564   beg((ptime(date(2005,Jan,7),hours(0))), zone);
1565 local_date_time
1566   end((ptime(date(2005,Feb,7),hours(0))), zone);
1567 local_time_period ltp(beg, end);
1568
1569 local_time_period res(jan_mst.merge(ltp));
1570 // res =&gt; 2005-Jan-07 00:00:00 through
1571 // 2005-Feb-06 23:59:59.999999999 (inclusive)</pre></td></tr>
1572 <tr>
1573 <td rowspan="2" valign="top"><pre class="screen">local_time_period span(local_time_period)</pre></td>
1574 <td>Combines two periods and any gap between them such that begin = min(p1.begin, p2.begin) and end = max(p1.end , p2.end).</td>
1575 </tr>
1576 <tr><td><pre class="screen">// using jan_mst period from previous example
1577
1578 local_date_time
1579   beg((ptime(date(2005,Mar,1),hours(0))), zone);
1580 local_date_time
1581   end((ptime(date(2005,Apr,1),hours(0))), zone);
1582 local_time_period mar_mst(beg, end);
1583
1584 local_time_period res(jan_mst.span(mar_mst));
1585 // res =&gt; 2005-Jan-01 00:00:00 through
1586 // 2005-Mar-31 23:59:59.999999999 (inclusive)</pre></td></tr>
1587 <tr>
1588 <td rowspan="2" valign="top"><pre class="screen">void shift(time_duration)</pre></td>
1589 <td>Add duration to both begin and end.</td>
1590 </tr>
1591 <tr><td><pre class="screen">local_date_time
1592   beg((ptime(date(2005,Mar,1),hours(0))), zone);
1593 local_date_time
1594   end((ptime(date(2005,Apr,1),hours(0))), zone);
1595 local_time_period mar_mst(beg, end);
1596
1597 mar_mst.shift(hours(48));
1598 // mar_mst =&gt; 2005-Mar-03 00:00:00 through
1599 // 2005-Apr-02 23:59:59.999999999 (inclusive)</pre></td></tr>
1600 </tbody>
1601 </table></div>
1602 <p>
1603   </p>
1604 <a name="local_time_period_operators"></a><h4>
1605 <a name="idp212662384"></a>Operators</h4>
1606 <p>
1607     </p>
1608 <div class="informaltable"><table class="table">
1609 <colgroup>
1610 <col>
1611 <col>
1612 </colgroup>
1613 <thead>
1614 <tr>
1615 <th rowspan="2" valign="top">Syntax</th>
1616 <th>Description</th>
1617 </tr>
1618 <tr><th>Example</th></tr>
1619 </thead>
1620 <tbody>
1621 <tr>
1622 <td rowspan="2" valign="top"><pre class="screen">operator==, operator!=</pre></td>
1623 <td>Equality operators. Periods are equal if ltp1.begin == ltp2.begin &amp;&amp; ltp1.last == ltp2.last</td>
1624 </tr>
1625 <tr><td><pre class="screen">if (ltp1 == ltp2) {...</pre></td></tr>
1626 <tr>
1627 <td rowspan="2" valign="top"><pre class="screen">operator&lt;</pre></td>
1628 <td>Ordering with no overlap. True if ltp1.end() less than ltp2.begin()</td>
1629 </tr>
1630 <tr><td><pre class="screen">if (ltp1 &lt; ltp2) {...</pre></td></tr>
1631 <tr>
1632 <td rowspan="2" valign="top"><pre class="screen">operator&gt;</pre></td>
1633 <td>Ordering with no overlap. True if ltp1.begin() greater than ltp2.end()</td>
1634 </tr>
1635 <tr><td><pre class="screen">if (ltp1 &gt; ltp2) {... etc</pre></td></tr>
1636 <tr>
1637 <td rowspan="2" valign="top"><pre class="screen">operator&lt;=, operator&gt;=</pre></td>
1638 <td>Defined in terms of the other operators.</td>
1639 </tr>
1640 <tr><td>&#160;</td></tr>
1641 </tbody>
1642 </table></div>
1643 <p>
1644   </p>
1645 </div>
1646 </div>
1647 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
1648 <td align="left"></td>
1649 <td align="right"><div class="copyright-footer">Copyright &#169; 2001-2005 CrystalClear Software, Inc<p>Subject to the Boost Software License, Version 1.0. (See accompanying file
1650     <code class="filename">LICENSE_1_0.txt</code> or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)</p>
1651 </div></td>
1652 </tr></table>
1653 <hr>
1654 <div class="spirit-nav">
1655 <a accesskey="p" href="posix_time.html"><img src="../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../date_time.html"><img src="../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="date_time_io.html"><img src="../../../doc/src/images/next.png" alt="Next"></a>
1656 </div>
1657 </body>
1658 </html>